Main Content

distance

Get distance at locations

Since R2023a

    Description

    dist = distance(map) returns the signed distances dist to the closest obstacle for all cells in the map map.

    dist = distance(map,location) returns the signed distances to the closest boundaries for the specified xy-locations location in world coordinates.

    Note

    Note that the distance function determines the distance using the interpolation method specified in InterpolationMethod property of map.

    dist = distance(map,location,frame) returns distances to the closest boundaries for the specified locations location in the coordinate frame frame.

    example

    [dist,isValid] = distance(map,location,___) returns isValid, indicating which of the specified locations location are within the map bounds isValid.

    dist = distance(map,cornerLocation,mapSize) returns the distances to the closest boundaries for a subregion of the map layer, map. The subregion starts in the corner location cornerLocation in the world coordinate frame with a given map size mapSize.

    dist = distance(map,cornerLocation,mapSize,frame) returns the distances to the closest boundaries for a subregion of the map layer, map. The subregion starts in the corner location cornerLocation in the coordinate frame frame.

    Note

    When specifying a corner location and map size, distance determines the distances between cell centers within the rectangular query region.

    Examples

    collapse all

    Load the exampleMaps MAT file.

    load exampleMaps.mat

    Create a signed distance map using the simpleMap data.

    sdm = signedDistanceMap(simpleMap,InterpolationMethod="none");
    show(sdm,BoundaryColor=[0 0 0],Colorbar="on");

    setMapData(sdm,[7 1],zeros(5,5))
    getMapData(sdm,[9 2])
    ans = logical
       0
    
    
    show(sdm,BoundaryColor=[0 0 0],Colorbar="on");

    Find the closest boundary to the coordinate, [16.25 6.25] and calculate the distance to the nearest boundary.

    coord = [16.25 6.25];
    boundary = closestBoundary(sdm,coord,"world")
    boundary = 
    boundary(:,:,1) =
    
       20.5000
    
    
    boundary(:,:,2) =
    
        6.5000
    
    
    dist = distance(sdm,coord)
    dist = 4
    

    Plot the line between the queried point and the closest obstacle cell center

    hold on
    plot([coord(1) boundary(:,:,1)],[coord(2) boundary(:,:,2)],"-r",Marker=".",MarkerSize=10)

    Note that even though distance from the queried point appears greater than 4 when plotted, the distance function calculates the distance from the nearest cell center of the queried point.

    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.

    Data Types: double

    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", cornerLocation is the top-left corner of the world frame.

    Data Types: double

    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.

    Data Types: double

    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

    Distances to closest obstacles, returned as an L-element column vector for location 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.

    If frame is either "world" or "local", then distance returns distances in Cartesian space.

    If frame is "grid", then distance returns distances in grid space.

    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.

    Extended Capabilities

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

    Version History

    Introduced in R2023a