getOccupancy

Get occupancy probability of locations

Syntax

occVal = getOccupancy(map,xy)

occVal = getOccupancy(map,xy,'local')

occVal = getOccupancy(map,ij,'grid')

[occVal,validPts] = getOccupancy(___)

occMatrix = getOccupancy(map)

occMatrix = getOccupancy(map,bottomLeft,matSize)

occMatrix = getOccupancy(map,bottomLeft,matSize,'local')

occMatrix = getOccupancy(map,topLeft,matSize,'grid')

Description

This MATLAB^® function returns the occupancy probability values of specified locations in an occupancy map.

occVal = getOccupancy(map,xy) returns an array of probability occupancy values at the xy locations in the world frame. Values close to 1 represent a high probability that the cell contains an obstacle. Values close to 0 represent a high probability that the cell is not occupied and obstacle free. Unknown locations, including outside the map, return map.DefaultValue.

occVal = getOccupancy(map,xy,'local') returns an array of occupancy values at the xy locations in the local frame.

occVal = getOccupancy(map,ij,'grid') specifies ij grid cell indices instead of xy locations.

[occVal,validPts] = getOccupancy(___) additionally outputs an n-element vector of logical values indicating whether input coordinates are within the map limits.

occMatrix = getOccupancy(map) returns all occupancy values in the map as a matrix.

occMatrix = getOccupancy(map,bottomLeft,matSize) returns a matrix of occupancy values by specifying the bottom-left corner location in world coordinates and the matrix size in meters.

occMatrix = getOccupancy(map,bottomLeft,matSize,'local') returns a matrix of occupancy values by specifying the bottom-left corner location in local coordinates and the matrix size in meters.

occMatrix = getOccupancy(map,topLeft,matSize,'grid') returns a matrix of occupancy values by specifying the top-left corner location in grid indices and the matrix size.

Examples

Insert Laser Scans into Occupancy Map

Create an empty occupancy grid map.

map = occupancyMap(10,10,20);

Specify the pose of the vehicle, ranges, angles, and the maximum range of the laser scan.

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

Create a lidarScan object with the specified ranges and angles.

scan = lidarScan(ranges,angles);

Insert the laser scan data into the occupancy map.

insertRay(map,pose,scan,maxrange);

Show the map to see the results of inserting the laser scan.

show(map)

Check the occupancy of the spot directly in front of the vehicle.

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,scan,maxrange);
show(map)

getOccupancy(map,[8 5])

ans = 
0.8448

Get Occupancy Values and Check Occupancy Status

Access occupancy values and check their occupancy status based on the occupied and free thresholds of the occupancyMap object.

Create a matrix and populate it with values. Use this matrix to create an occupancy map.

p = 0.5*ones(20,20);
p(11:20,11:20) = 0.75*ones(10,10);
map = occupancyMap(p,10);

Get the occupancy of different locations and check their occupancy statuses. The occupancy status returns 0 for free space and 1 for occupied space. Unknown values return –1.

pocc = getOccupancy(map,[1.5 1])

pocc = 
0.7500

occupied = checkOccupancy(map,[1.5 1])

occupied = 
1

pocc2 = getOccupancy(map,[5 5],'grid')

pocc2 = 
0.5000

occupied2 = checkOccupancy(map,[5 5],'grid')

occupied2 = 
-1

Input Arguments

map — Map representation

occupancyMap object

Map representation, specified as a occupancyMap object. This object represents the environment of the vehicle. The object contains a matrix grid with values representing the probability of the occupancy of that cell. Values close to 1 represent a high probability that the cell contains an obstacle. Values close to 0 represent a high probability that the cell is not occupied and obstacle free.

xy — World coordinates

n-by-2 matrix

World coordinates, specified as an n-by-2 matrix of [x y] pairs, where n is the number of world coordinates.

Data Types: double

ij — Grid positions

n-by-2 matrix

Grid positions, specified as an n-by-2 matrix of [i j] pairs in [rows cols] format, where n is the number of grid positions.

Data Types: double

bottomLeft — Location of output matrix in world or local

two-element vector | [xCoord yCoord]

Location of bottom left corner of output matrix in world or local coordinates, specified as a two-element vector, [xCoord yCoord]. Location is in world or local coordinates based on syntax.

Data Types: double

matSize — Output matrix size

two-element vector | [xLength yLength] | [gridRow gridCol]

Output matrix size, specified as a two-element vector, [xLength yLength] or [gridRow gridCol]. Size is in world, local, or grid coordinates based on syntax.

Data Types: double

topLeft — Location of grid

two-element vector | [iCoord jCoord]

Location of top left corner of grid, specified as a two-element vector, [iCoord jCoord].

Data Types: double

Output Arguments

occVal — Probability occupancy values

column vector

Probability occupancy values, returned as a column vector the same length as either xy or ij.

Values close to 0 represent a high probability that the cell is not occupied and obstacle free.

validPts — Valid map locations

n-by-1 column vector

Valid map locations, returned as an n-by-1 column vector equal in length to xy or ij. Locations inside the map return a value of 1. Locations outside the map limits return a value of 0.

occMatrix — Matrix of occupancy values

matrix

Matrix of occupancy values, returned as matrix with size equal to matSize or the size of map.

Values close to 0 represent a high probability that the cell is not occupied and obstacle free.

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 memory when storing large maps in MATLAB. When calling setOccupancy and then getOccupancy, 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™.

Version History

Introduced in R2019b