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)

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 proeprty 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

`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

expand all

`GridSize` — Number of rows and columns in grid
two-element horizontal vector

This property is read-only.

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

`Resolution` — Grid resolution
1 (default) | scalar in cells per meter

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

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.

`YLocalLimits` — Minimum and maximum values of y-coordinates in local frame
two-element vector

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.

`XWorldLimits` — Minimum and maximum values of x-coordinates in world frame
two-element vector

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.

`YWorldLimits` — Minimum and maximum values of y-coordinates
two-element vector

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

`checkOccupancy`	Check occupancy values for locations
`getOccupancy`	Get occupancy value of locations
`grid2local`	Convert grid indices to local coordinates
`grid2world`	Convert grid indices to world coordinates
`inflate`	Inflate each occupied grid 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`	Show occupancy grid values
`syncWith`	Sync map with overlapping map
`world2grid`	Convert world coordinates to grid indices
`world2local`	Convert world coordinates to local coordinates

Examples

collapse all

Create and Modify Binary Occupancy Grid

Open Live Script

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

Open Live Script

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

Open Live Script

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