# closestBoundary

Get nearest boundary to location

Since R2023a

## Syntax

``boundary = closestBoundary(map)``
``boundary = closestBoundary(map,location)``
``boundary = closestBoundary(map,location,frame)``
``[boundary,isValid] = closestBoundary(map,location,___)``
``boundary = closestBoundary(map,cornerLocation,matSize)``
``boundary = closestBoundary(map,cornerLocation,matSize,frame)``

## Description

````boundary = closestBoundary(map)` returns the locations of the closest obstacles `boundary` for each cell of the specified signed distance map `map`.```
````boundary = closestBoundary(map,location)` returns the closest boundary locations for the specified xy-locations `locations` in world coordinates.```

example

````boundary = closestBoundary(map,location,frame)` returns the closest boundary locations for the specified locations `locations` in the coordinate frame `frame`.```
````[boundary,isValid] = closestBoundary(map,location,___)` returns `isValid`, indicating which of the specified locations `locations` are within the map bounds.```
````boundary = closestBoundary(map,cornerLocation,matSize)` returns the closest boundary locations for a subregion of the signed distance map, `map`. The subregion starts in the minimum corner location `cornerLocation` in the world coordinate frame with a given map size `matSize`.```
````boundary = closestBoundary(map,cornerLocation,matSize,frame)` returns the closest boundary locations for a subregion of the signed distance map, `map`. The subregion starts in the minimum corner location `cornerLocation` in the coordinate frame `frame`. NoteWhen specifying a corner location and map size, `closestBoundary` determines the closest boundary locations using the distances between cell centers within the rectangular query region. ```

## Examples

collapse all

Create a signed distance map with a width of 40 cells and a height of 20 cells.

`map = signedDistanceMap(40,20);`

Update the map occupancy with an identity matrix.

```setMapData(map,[1 10],eye(20),"grid"); show(map);```

Find nearest boundary for each corner cell of map.

```queryIJ = [1 1; 20 1; 1 40; 20 40]; nearestCornerIJ = closestBoundary(map,queryIJ,"grid")```
```nearestCornerIJ = nearestCornerIJ(:,:,1) = 1 6 16 20 nearestCornerIJ(:,:,2) = 10 15 25 29 ```

Find nearest XY boundary cell for cells in the first 5-by-5 quadrant in the top-left.

`nearestQuadrantXY = closestBoundary(map,[0 5],[5 5])`
```nearestQuadrantXY = nearestQuadrantXY(:,:,1) = 9.5000 10.5000 10.5000 11.5000 11.5000 10.5000 10.5000 11.5000 11.5000 12.5000 10.5000 11.5000 11.5000 12.5000 12.5000 11.5000 11.5000 12.5000 12.5000 13.5000 11.5000 12.5000 12.5000 13.5000 13.5000 nearestQuadrantXY(:,:,2) = 19.5000 18.5000 18.5000 17.5000 17.5000 18.5000 18.5000 17.5000 17.5000 16.5000 18.5000 17.5000 17.5000 16.5000 16.5000 17.5000 17.5000 16.5000 16.5000 15.5000 17.5000 16.5000 16.5000 15.5000 15.5000 ```

## Input Arguments

collapse all

Signed distance map, specified as a `signedDistanceMap` object.

World or local coordinates, or grid locations, specified as an N-by-2 matrix. N is the number of locations. The format of the rows depends on the value of the `frame` argument:

• `"world"` — [x y] coordinates in the world frame.

• `"local"` — [x y] coordinates in the local frame.

• `"grid"` — [row column] location in the grid frame.

Minimum corner location of output matrix, specified as a two-element vector of coordinates in the form, [x y]. The location is in world or local coordinates if the `frame` argument is set to `"world"` and `"local"`, respectively. When `frame` is `"grid"`, the coordinates are in the form [row column] and `cornerLocation` is the top-left corner of the world frame.

Subregion map size, specified as a two-element vector [x y] in world or local coordinates. Location is in world or local coordinates if the `frame` argument is set to `"world"` and `"local"`, respectively. When `frame` is `"grid"`, `cornerLocation` is the top-left corner of the world frame.

Coordinate frame, specified as one of these options:

• `"world"` — Specify coordinates in the world frame.

• `"local"` — Specify coordinates in the local frame.

• `"grid"` — Specify grid locations in the grid frame.

Data Types: `char` | `string`

## Output Arguments

collapse all

Nearest boundary point, returned as an L-by-1-by-2 array for point queries and an M-by-N-by-2 array for subregion queries. L is the number of locations queried. M and N are the dimensions of the map or specified map subregion.

Points in boundary, returned as an L-element vector, where L is the total number of queried locations. Each element is a `1` (`true`) if the point is within the boundaries, and `0` (`false`) if the point is outside boundaries.

This output is only returned for point queries.

## Version History

Introduced in R2023a