checkOccupancy

Check if locations are free or occupied

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

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

Version History

Introduced in R2019b