cost

Retrieve data from traversability map layer

Since R2025a

collapse all in page

Syntax

mapData = cost(map)
mapData = cost(map,xy,"local")
mapData = cost(map,ij,"grid")
mapData = cost(map,bottomLeft,mapSize)
mapData = cost(map,bottomLeft,mapSize,"local")
mapData = cost(map,topLeft,gridSize,"grid")

Description

mapData = cost(map) returns a matrix of values that contains all the data for the given map layer map.

example

mapData = cost(map,xy,"local") returns an array of values for the given xy-locations in local coordinates. If xy-locations fall outside the range of the map limits, then map data outputs NaN.

mapData = cost(map,ij,"grid") returns an array of values for the given ij-locations in grid coordinates. Each row of ij refers to a grid cell index [i j]. If ij-locations fall outside the range of the map limits, then map data outputs NaN.

mapData = cost(map,bottomLeft,mapSize) returns a matrix of values in a subregion of the map layer, map. The subregion starts in the bottom-left xy-position bottomLeft in world coordinates with a given map size mapSize specified as [width height] in meters.

mapData = cost(map,bottomLeft,mapSize,"local") specifies the bottom-left corner of the subregion in local coordinates.

mapData = cost(map,topLeft,gridSize,"grid") specifies the top-left corner of the sub region in grid coordinates. The subregion size, gridSize is also given in grid coordinates as [rows cols].

Examples

collapse all

This example uses:

Open Live Script

Create traversability map with a sample digital elevation model (DEM) and set the map resolution.

The resolution sets the size of each grid cell in meters. A smaller value of resolution gives finer details.

resolution = 1.25; % cells per meter
[xdata, ydata] = meshgrid(0:resolution:100, flip(0:resolution:100)); % x and y axes data of the terrain
elevationModel = peaks(size(xdata,1)); % Terrain elevation in meters
elevationModel(elevationModel<0) = 0; % Discard valleys

Visualize digital elevation model (DEM) of the terrain.

figure;
surf(xdata, ydata, elevationModel, EdgeColor="none");
xlabel('X [m]')
ylabel('Y [m]')
zlabel('Elevation [m]')
view(2)
colorbar

Create traversability map from the digital elevation model (DEM).

map = traversabilityMap(elevationModel, resolution)
map = 
  traversabilityMap with properties:

          SlopeThreshold: [0.2000 0.3000]
      RoughnessThreshold: [0.1000 0.2000]
     StepHeightThreshold: [1.1352 1.7323]
    StepHeightWindowSize: 5.6000
              CostWeight: [1 1 1]
       GridOriginInLocal: [0 0]
              Resolution: 1.2500
            XLocalLimits: [0 64.8000]
            YLocalLimits: [0 64.8000]

Display the traversability map.

show(map, "local")

Enable SlopeThreshold and set the safe and critical values.

Flexible threshold values allow intermediate terrains with moderate slopes (e.g., between 10° and 15°) to have a cost but remain traversable. In this case, areas with slope ≤ 10° are considered safe whereas areas with slope > 15° are non-traversable. Areas between the safe and critical thresholds are assigned intermediate cost values.

safeSlope = 10 * pi / 180;
criticalSlope = 15 * pi / 180;
map.SlopeThreshold = [safeSlope, criticalSlope];

Set the StepHeightThreshold and RoughnessThreshold to infinity to disable their influence.

map.StepHeightThreshold = inf; % No limit on step height
map.RoughnessThreshold = inf; % No limit on roughness

Display the updated traversability map in the local coordinate frame.

show(map, "local")

Access traversability data for analysis or debugging. Extract the data for a window whose bottom-left corner is at [X,Y] = [20,30] metres and its [Width,Height] = [5,7] metres.

costData = cost(map, [20,30], [5,7]);
disp("Traversability Cost Data:");
Traversability Cost Data:

disp(costData);
    0.8802    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000
         0    1.0000    1.0000    1.0000    1.0000    1.0000    1.0000
         0         0    1.0000    1.0000    1.0000    1.0000    1.0000
         0         0         0    1.0000    1.0000    1.0000    1.0000
         0         0         0    0.7495    1.0000    1.0000    1.0000
         0         0         0         0    1.0000    1.0000    1.0000
         0         0         0         0         0    1.0000    1.0000
         0         0         0         0         0    0.8712    1.0000
         0         0         0         0         0         0    1.0000

To configure strict slope threshold, set identical values for safe and critical threshold limits. This use case is applicable for offroad vehicles designed for flat terrains or with low tolerance for inclines.

strictSlope = 10 * pi / 180;
map.SlopeThreshold = [strictSlope, strictSlope];

Visualize the updated traversability map. You can access the traversability data by using getMapData.

show(map, "local")

Input Arguments

collapse all

Map layer, specified as a mapLayer (Navigation Toolbox) object.

World or local coordinates, specified as an N-by-2 matrix of [x y] pairs, where N is the number of 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

Subregion map size, specified as a two-element vector [x y] in world or local coordinates.

Data Types: double

Output grid size, specified as a two-element vector [row col].

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

Data values from map layer, returned as a matrix. By default, the function returns all data on the layer as an M-by-N matrix. M and N are the grid rows and columns respectively.

Extended Capabilities

expand all

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

Version History

Introduced in R2025a

See Also

Objects

Functions