Main Content

checkOccupancy

Check if locations are free or occupied

collapse all in page

Syntax

iOccval = checkOccupancy(map,xy)
iOccval = checkOccupancy(map,xy,'local')
iOccval = checkOccupancy(map,ij,'grid')
[iOccval,validPts] = checkOccupancy(___)
occMatrix = checkOccupancy(map)
occMatrix = checkOccupancy(map,bottomLeft,matSize)
occMatrix = checkOccupancy(map,bottomLeft,matSize,'local')
occMatrix = checkOccupancy(map,topLeft,matSize,'grid')

Description

This MATLAB® function returns the occupancy status of specified locations in an occupancy map.

iOccval = checkOccupancy(map,xy) returns an array of occupancy values at the xy locations. Each row is a separate xy location in the grid. Occupancy values can be obstacle free (0), occupied (1), or unknown (–1) based on the OccupiedThreshold and FreeThreshold properties of the map object.

example

iOccval = checkOccupancy(map,xy,'local') returns an array of occupancy values at the xy locations in the local frame. The local frame is based on the LocalOriginInWorld property of the map.

example

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

example

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

occMatrix = checkOccupancy(map) returns a matrix that contains the occupancy status of each location. Obstacle-free cells return 0, occupied cells return 1. Unknown locations, including outside the map, return -1.

occMatrix = checkOccupancy(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 = checkOccupancy(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 = checkOccupancy(map,topLeft,matSize,'grid') returns a matrix of occupancy values by specifying the top-left corner location in grid coordinates and the grid size.

Examples

collapse all

Open Live Script

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

collapse all

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 certainty that the cell contains an obstacle. Values close to 0 represent certainty that the cell is not occupied and obstacle free.

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

Data Types: double

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

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

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

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

Data Types: double

Output Arguments

collapse all

Interpreted occupancy values, returned as an n-by-1 column vector equal in length to xy or ij.

Occupancy values can be obstacle free (0), occupied (1), or unknown (–1). These values are determined from the actual probability values and the OccupiedThreshold and FreeThreshold properties of the map object.

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.

Matrix of occupancy values, returned as matrix with size equal to matSize or the size of your map. Occupancy values can be obstacle free (0), occupied (1), or unknown (-1).

Extended Capabilities

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

Version History

Introduced in R2019b

See Also

| | (Robotics System Toolbox)