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

Syntax

map = binaryOccupancyMap

map = binaryOccupancyMap(width,height)

map = binaryOccupancyMap(width,height,resolution)

map = binaryOccupancyMap(rows,cols,resolution,"grid")

map = binaryOccupancyMap(p)

map = binaryOccupancyMap(p,resolution)

map = binaryOccupancyMap(sourcemap)

map = binaryOccupancyMap(sourcemap,resolution)

map = binaryOccupancyMap(___,Name=Value)

Description

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.

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).

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.

map = binaryOccupancyMap(___,Name=Value) sets properties using one or more name-value arguments.

Input Arguments

width — Map width

positive scalar

Map width, specified as a positive scalar in meters.

height — Map height

positive scalar

Map height, specified as a positive scalar in meters.

p — Map grid values

matrix

Map grid values, specified as a matrix.

sourcemap — Occupancy map object

binaryOccupancyMap object

Occupancy map object, specified as a binaryOccupancyMap object.

Properties

GridSize — Number of rows and columns in grid

two-element vector of form [rows cols]

This property is read-only.

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

Resolution — Grid resolution

1 (default) | scalar

This property is read-only.

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

XLocalLimits — Minimum and maximum values of x-coordinates in local frame

two-element vector of form [min max]

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.

YLocalLimits — Minimum and maximum values of y-coordinates in local frame

two-element vector of form [min max]

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.

XWorldLimits — Minimum and maximum values of x-coordinates in world frame

two-element vector of form [min max]

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.

YWorldLimits — Minimum and maximum values of y-coordinates

two-element vector of form [min max]

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.

GridLocationInWorld — Location of the grid in world coordinates

[0 0] (default) | two-element vector | [xGrid yGrid]

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

LocalOriginInWorld — Location of the local frame in world coordinates

[0 0] (default) | two-element vector | [xWorld yWorld]

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.

GridOriginInLocal — Location of the grid in local coordinates

[0 0] (default) | two-element vector | [xLocal yLocal]

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

DefaultValue — Default value for unspecified map locations

0 (default) | 1

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

Object Functions

copy	Create copy of binary occupancy map
checkOccupancy	Check if locations are free or occupied
getOccupancy	Get occupancy value of locations
grid2local	Convert grid indices to local coordinates
grid2world	Convert grid indices to world coordinates
inflate	Inflate each occupied location
insertRay	Insert ray from laser scan observation
local2grid	Convert local coordinates to grid indices
local2world	Convert local coordinates to world coordinates
move	Move map in world frame
occupancyMatrix	Convert occupancy grid to matrix
raycast	Compute cell indices along a ray
rayIntersection	Find intersection points of rays and occupied map cells
setOccupancy	Set occupancy value of locations
show	Display binary occupancy map
syncWith	Sync map with overlapping map
world2grid	Convert world coordinates to grid indices
world2local	Convert world coordinates to local coordinates

Examples

Create and Modify Binary Occupancy Grid

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)

Image to Binary Occupancy Grid Example

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)

Convert PGM Image to Map

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)

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

As of MATLAB^® R2022a, default map behavior during code generation has changed, which may result in backwards compatibility issues. Maps such as binaryOccupancyMap now support fixed-size code generation (DynamicMemoryAllocation="off").

1. Maps that are either default-constructed or constructed with compile-time constant size information (or matrices that are of compile-time constant size) produce fixed-size maps.

2. To restore the previous behavior, use the coder.ignoreConst (MATLAB Coder) function when specifying size inputs, or coder.varsize (MATLAB Coder) matrix variable name specified as a string scalar or character vector, prior to constructing the map.

Version History

Introduced in R2015a

R2019b: binaryOccupancyMap was renamed

The binaryOccupancyMap object was renamed from robotics.BinaryOccupancyGrid. Use binaryOccupancyMap for all object creation.