robotics.OccupancyGrid class

Package: robotics

Create occupancy grid with probabilistic values

Description

OccupancyGrid creates a 2-D occupancy grid map. Each cell in the occupancy grid has a value representing the probability of the occupancy of that cell. Values close to 1 represent a high certainty that the cell contains an obstacle. Values close to 0 represent certainty that the cell is not occupied and obstacle free.

Occupancy grids are used in robotics algorithms such as path planning (see robotics.PRM). They are also used in mapping applications for finding collision-free paths, performing collision avoidance, and calculating localization (see robotics.MonteCarloLocalization). You can modify your occupancy grid to fit your specific application.

The OccupancyGrid objects support world and grid coordinates. The world coordinates origin is defined by the GridLocationInWorld property of the object, which defines the bottom-left corner of the grid. The number and size of grid locations are defined by the Resolution property. The first grid location with index (1,1) begins in the top-left corner of the grid.

Use the OccupancyGrid class to create 2-D maps of an environment with probability values representing different obstacles in your world. You can specify exact probability values of cells or include observations from sensors such as laser scanners.

Probability values are stored using a binary Bayes filter to estimate the occupancy of each grid cell. A log-odds representation is used, with values stored as int16 to reduce the map storage size and allow for real-time applications.

If memory size is a limitation, consider using robotics.BinaryOccupancyGrid instead. The binary occupancy grid uses less memory with binary values, but still works with Robotics System Toolbox™ algorithms and other applications.

Construction

map = robotics.OccupancyGrid(width,height) creates a 2-D occupancy grid object representing a world space of width and height in meters. The default grid resolution is 1 cell per meter.

map = robotics.OccupancyGrid(width,height,resolution) creates an occupancy grid with a specified grid resolution in cells per meter.

map = robotics.OccupancyGrid(rows,cols,resolution,"grid") creates an occupancy grid with the specified number of rows and columns and with the resolution in cells per meter.

map = robotics.OccupancyGrid(p) creates an occupancy grid from the values in matrix p. The grid size matches the size of the matrix, with each cell probability value interpreted from the matrix location.

map = robotics.OccupancyGrid(p,resolution) creates an occupancy grid from the specified matrix and resolution in cells per meter.

Input Arguments

expand all

Map width, specified as a scalar in meters.

Data Types: double

Map height, specified as a scalar in meters.

Data Types: double

Grid resolution, specified as a scalar in cells per meter.

Data Types: double

Input occupancy grid, specified as a matrix of probability values from 0 to 1. The size of the grid matches the size of the matrix. Each matrix element corresponds to the probability of the grid cell location being occupied. Values close to 0 represent a high certainty that the cell contains an obstacle. Values close to 1 represent certainty that the cell is not occupied and obstacle free.

Data Types: double

Properties

expand all

Threshold to consider cells as obstacle-free, specified as a scalar. Probability values below this threshold are considered obstacle free. This property also defines the free locations for path planning when using robotics.PRM.

Threshold to consider cells as occupied, specified as a scalar. Probability values above this threshold are considered occupied.

Saturation limits for probability, specified as a [min max] vector. Values above or below these saturation values are set to the min and max values. This property reduces oversaturating of cells when incorporating multiple observations.

This property is read-only.

Number of rows and columns in grid, stored as a [rows cols] vector.

Grid resolution, stored as a scalar in cells per meter. This value is read only.

Minimum and maximum world range values of x-coordinates, stored as a [min max] vector. This value is read only.

Minimum and maximum world range values of y-coordinates, stored as a [min max] vector. This value is read only.

[x,y] world coordinates of the bottom-left corner of the grid, specified as a two-element vector.

Methods

checkOccupancyCheck locations for free, occupied, or unknown values
copyCreate copy of occupancy grid
getOccupancyGet occupancy of a location
grid2worldConvert grid indices to world coordinates
inflateInflate each occupied grid location
insertRayInsert ray from laser scan observation
occupancyMatrixConvert occupancy grid to double matrix
rayIntersectionCompute map intersection points of rays
raycastCompute cell indices along a ray
setOccupancySet occupancy of a location
showShow grid values in a figure
updateOccupancyIntegrate probability observation at a location
world2gridConvert world coordinates to grid indices

Examples

collapse all

Take range and angle readings from a laser scan and insert these readings into an occupancy grid.

Create an empty occupancy grid map.

map = robotics.OccupancyGrid(10,10,20);

Insert a laser scan into the occupancy grid. Specify the pose of the robot ranges and angles and the max range of the laser scan.

pose = [5,5,0];
ranges = 3*ones(100, 1);
angles = linspace(-pi/2, pi/2, 100);
maxrange = 20;
        
insertRay(map,pose,ranges,angles,maxrange);

Show the map to see the results of inserting the laser scan. Check the occupancy of the spot directly in front of the robot.

show(map)

getOccupancy(map,[8 5])
ans = 0.7000

Add a second reading and view the update to the occupancy values. The additional reading increases the confidence in the readings. The free and occupied values become more distinct.

insertRay(map,pose,ranges,angles,maxrange);
show(map)

getOccupancy(map,[8 5])
ans = 0.8448

Convert a portable graymap (.pgm) file containing a ROS map into an OccupancyGrid map for use in MATLAB.

Import the image using imread. Crop the image to the relevant area.

image = imread('playpen_map.pgm');
imageCropped = image(750:1250,750:1250);
imshow(imageCropped)

PGM values are expressed from 0 to 255 as uint8. Normalize these values by converting the cropped image to double and dividing each cell by 255. This image shows obstacles as values close to 0. Subtract the normalized image from 1 to get occupancy values with 1 representing occupied space.

imageNorm = double(imageCropped)/255;
imageOccupancy = 1 - imageNorm;

Create the OccupancyGrid object using an adjusted map image. The imported map resolution is 20 cells per meter.

map = robotics.OccupancyGrid(imageOccupancy,20);
show(map)

Limitations

Occupancy values have a limited resolution of ±0.001. The values are stored as int16 using a log-odds representation. This data type limits resolution, but saves you memory when storing large maps in MATLAB®. When calling set and then get, the value returned might not equal the value you set. For more information, see the log-odds representations section in Occupancy Grids.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Introduced in R2016b