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(p,resolution) creates an object 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 horizontal 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 horizontal 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 horizontal 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 horizontal 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

checkOccupancyCheck occupancy values for locations
getOccupancyGet occupancy value of locations
grid2localConvert grid indices to local coordinates
grid2worldConvert grid indices to world coordinates
inflateInflate each occupied grid 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
showShow occupancy grid values
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)

Inflate occupied locations by a given radius.

inflate(map, 0.5)
figure
show(map)

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)

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)

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)

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)

Create binaryOccupancyMap object using adjusted map image.

map = binaryOccupancyMap(imageBW);
show(map)

Compatibility Considerations

expand all

Behavior change in future release

Extended Capabilities

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

Introduced in R2015a