Main Content

binaryOccupancyMap

Create occupancy grid with binary values

Description

The binaryOccupancyMap creates a 2-D occupancy map object, which you can use to represent and visualize a robot workspace, including obstacles. The integration of sensor data and position estimates create a spatial representation of the approximate locations of the obstacles.

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

Each cell in the occupancy grid has a value representing the occupancy status of that cell. An occupied location is represented as true (1) and a free location is represented as false (0).

The object keeps track of three reference frames: world, local, and, grid. The world frame origin is defined by GridLocationInWorld, which defines the bottom-left corner of the map relative to the world frame. The LocalOriginInWorld property specifies the location of the origin of the local frame relative to the world frame. The first grid location with index (1,1) begins in the top-left corner of the grid.

Note

This object was previously named robotics.BinaryOccupancyGrid.

Creation

Description

example

map = binaryOccupancyMap creates a 2-D binary occupancy grid with a width and height of 10m. The default grid resolution is one cell per meter.

example

map = binaryOccupancyMap(width,height) creates a 2-D binary occupancy grid representing a work space of width and height in meters. The default grid resolution is one cell per meter.

map = binaryOccupancyMap(width,height,resolution) creates a grid with the Resolution property specified in cells per meter. The map is in world coordinates by default.

map = binaryOccupancyMap(rows,cols,resolution,"grid") creates a 2-D binary occupancy grid of size (rows,cols).

example

map = binaryOccupancyMap(p) creates a grid from the values in matrix p. The size of the grid matches the size of the matrix, with each cell value interpreted from its location in the matrix. p contains any numeric or logical type with zeros (0) and ones (1).

map = binaryOccupancyMap(p,resolution) creates a map from a matrix with the Resolution property specified in cells per meter.

map = binaryOccupancyMap(sourcemap) creates an object using values from another binaryOccupancyMap object.

map = binaryOccupancyMap(sourcemap,resolution) creates an object using values from another binaryOccupancyMap object, but resamples the matrix to have the specified resolution.

Input Arguments

expand all

Map width, specified as a positive scalar in meters.

Map height, specified as a positive scalar in meters.

Map grid values, specified as a matrix.

Occupancy map object, specified as a binaryOccupancyMap object.

Properties

expand all

This property is read-only.

Number of rows and columns in grid, stored as a two-element vector of the form [rows cols].

This property is read-only.

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

This property is read-only.

Minimum and maximum values of x-coordinates in local frame, stored as a two-element vector of the form [min max]. Local frame is defined by LocalOriginInWorld property.

This property is read-only.

Minimum and maximum values of y-coordinates in local frame, stored as a two-element vector of the form [min max]. Local frame is defined by LocalOriginInWorld property.

This property is read-only.

Minimum and maximum values of x-coordinates in world frame, stored as a two-element vector of the form [min max]. These values indicate the world range of the x-coordinates in the grid.

This property is read-only.

Minimum and maximum values of y-coordinates, stored as a two-element vector of the form [min max]. These values indicate the world range of the y-coordinates in the grid.

Location of the bottom-left corner of the grid in world coordinates, specified as a two-element vector, [xGrid yGrid].

Location of the origin of the local frame in world coordinates, specified as a two-element vector, [xLocal yLocal]. Use the move function to shift the local frame as your vehicle moves.

Location of the bottom-left corner of the grid in local coordinates, specified as a two-element vector, [xLocal yLocal].

Default value for unspecified map locations including areas outside the map, specified as 0 or 1.

Object Functions

copyCreate copy of binary occupancy map
checkOccupancyCheck if locations are free or occupied
getOccupancyGet occupancy value of locations
grid2localConvert grid indices to local coordinates
grid2worldConvert grid indices to world coordinates
inflateInflate each occupied location
insertRayInsert ray from laser scan observation
local2gridConvert local coordinates to grid indices
local2worldConvert local coordinates to world coordinates
moveMove map in world frame
occupancyMatrixConvert occupancy grid to matrix
raycastCompute cell indices along a ray
rayIntersectionFind intersection points of rays and occupied map cells
setOccupancySet occupancy value of locations
showDisplay binary occupancy map
syncWithSync map with overlapping map
world2gridConvert world coordinates to grid indices
world2localConvert world coordinates to local coordinates

Examples

collapse all

Create a 10m x 10m empty map.

map = binaryOccupancyMap(10,10,10);

Set occupancy of world locations and show map.

x = [1.2; 2.3; 3.4; 4.5; 5.6];
y = [5.0; 4.0; 3.0; 2.0; 1.0];

setOccupancy(map, [x y], ones(5,1))
figure
show(map)

Figure contains an axes object. The axes object with title Binary Occupancy Grid, xlabel X [meters], ylabel Y [meters] contains an object of type image.

Inflate occupied locations by a given radius.

inflate(map, 0.5)
figure
show(map)

Figure contains an axes object. The axes object with title Binary Occupancy Grid, xlabel X [meters], ylabel Y [meters] contains an object of type image.

Get grid locations from world locations.

ij = world2grid(map, [x y]);

Set grid locations to free locations.

setOccupancy(map, ij, zeros(5,1), 'grid')
figure
show(map)

Figure contains an axes object. The axes object with title Binary Occupancy Grid, xlabel X [meters], ylabel Y [meters] contains an object of type image.

This example shows how to convert an image to a binary occupancy grid for using with mapping and path planning.

Import image.

image = imread('imageMap.png');

Convert to grayscale and then black and white image based on given threshold value.

grayimage = rgb2gray(image);
bwimage = grayimage < 0.5;

Use black and white image as matrix input for binary occupancy grid.

grid = binaryOccupancyMap(bwimage);

show(grid)

Figure contains an axes object. The axes object with title Binary Occupancy Grid, xlabel X [meters], ylabel Y [meters] contains an object of type image.

This example shows how to convert a .pgm file into a binaryOccupancyMap object for use in MATLAB.

Import image using imread. The image is quite large and should be cropped to the relevant area.

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

Figure contains an axes object. The axes object contains an object of type image.

Unknown areas (gray) should be removed and treated as free space. Create a logical matrix based on a threshold. Depending on your image, this value could be different. Occupied space should be set as 1 (white in image).

imageBW = imageCropped < 100;
imshow(imageBW)

Figure contains an axes object. The axes object contains an object of type image.

Create binaryOccupancyMap object using adjusted map image.

map = binaryOccupancyMap(imageBW);
show(map)

Figure contains an axes object. The axes object with title Binary Occupancy Grid, xlabel X [meters], ylabel Y [meters] contains an object of type image.

Extended Capabilities

Version History

Introduced in R2015a

expand all