addlink

Add links between one or more state pairs

Since R2024a

Syntax

linkIDs = addlink(graph,statePairs)

linkIDs = addlink(graph,statePairs,metadata1,...metadataN)

[linkIDs,status] = addlink(___)

Description

linkIDs = addlink(graph,statePairs) adds links between one or more state pairs in the input graph specified as a navGraph object.

linkIDs = addlink(graph,statePairs,metadata1,...metadataN) adds links between two states in the graph and adds the associated metadata information to the links table of the input graph. Use this syntax when the links table has multiple columns with metadata, such as Weights, in addition to the state pairs. However, the first column of the table must always specify the state pairs to be connected.

[linkIDs,status] = addlink(___) also returns status, indicating whether the new links were successfully added to the graph. If the newly specified links conflict with the existing links in the graph, the function ignores the conflicting links and the existing links remain unchanged.

Examples

Add Links Between Two States in Graph

Load navGraph object into MATLAB® workspace and inspect its properties.

load("navGraphData.mat")
disp(navGraphObj)

  navGraph with properties:

           States: [8×3 table]
            Links: [7×3 table]
    LinkWeightFcn: @nav.algs.distanceEuclidean

Inspect the states table of the graph.

disp(navGraphObj.States)

          StateVector          Name     Lanes
    _______________________    _____    _____

    8          2    0.72176    {'A'}      2  
    1          1    0.29188    {'B'}      2  
    7          7    0.91777    {'C'}      2  
    8         10    0.71458    {'D'}      2  
    5          1    0.54254    {'E'}      2  
    3          6    0.14217    {'F'}      2  
    2          9    0.37334    {'G'}      3  
    8          7    0.67413    {'H'}      2  

Inspect the links table of the graph. The first column contains the indices of states from the states table. The two-element vectors in the first column of the table represent the pairs of states that are connected. Note that the links table also contains 'Weight' and 'Curvature' metadata in addition to the connected state pairs.

disp(navGraphObj.Links)

    EndStates    Weight    Curvature
    _________    ______    _________

     1    3      1.5089    0.0034635
     3    7       8.921    0.0063649
     5    4       2.387    0.0060558
     6    2      19.452    0.0041751
     7    1      38.776    0.0051347
     7    8      13.938    0.0076324
     8    2      43.893    0.0031493

Display the graph.

show(navGraphObj)

From the graph, you can infer that the states 'D' and 'E' are not connected to any other states, and no path exists when a start or goal point lies on one of these states. To connect these states, use the addlink function. Specify the state pairs to be connected using either the indices or state names from the states table.

Specify State Indices to Add Links

From the states table of the input graph you can find that the indices for the states with names "E" and "F" are 5 and 6, respectively. Specify these indices as input to connect states "E" and "F".

Id = addlink(navGraphObj,[5 6],2.5,0.001)

Id = 
4

Inspect the updated links table for new states and the related metadata. Note that the state indices of the new state pairs are added to the fifth row of the links table. The entries in the links table are sorted according to the index of the first state in each state pair listed in the first column. The rows that have the same index for the first state are sorted based on the index of the second state in each state pair.

disp(navGraphObj.Links)

    EndStates    Weight    Curvature
    _________    ______    _________

     1    3      1.5089    0.0034635
     3    7       8.921    0.0063649
     5    4       2.387    0.0060558
     5    6         2.5        0.001
     6    2      19.452    0.0041751
     7    1      38.776    0.0051347
     7    8      13.938    0.0076324
     8    2      43.893    0.0031493

Display the updated graph. Now all the states in the input graph are connected, you can compute path for any start and goal point that lie between these states.

show(navGraphObj)

Specify State Names to Add Links

Add a link between states with names "C" and "D". In addition to the state pair, you must also specify the value for associated Weight and Curvature metadata in the links table.

Id = addlink(navGraphObj,["C" "D"],5,0.004)

Id = 
2

Inspect the updated links table for new state pairs and the related metadata. Note that the state indices of the new state pairs are added to the second row of the links table.

disp(navGraphObj.Links)

    EndStates    Weight    Curvature
    _________    ______    _________

     1    3      1.5089    0.0034635
     3    4           5        0.004
     3    7       8.921    0.0063649
     5    4       2.387    0.0060558
     5    6         2.5        0.001
     6    2      19.452    0.0041751
     7    1      38.776    0.0051347
     7    8      13.938    0.0076324
     8    2      43.893    0.0031493

show(navGraphObj)

Add Links Between Multiple States in Graph

Load navGraph object into MATLAB® workspace and inspect its properties.

load("navGraphData.mat")
disp(navGraphObj)

  navGraph with properties:

           States: [8×3 table]
            Links: [7×3 table]
    LinkWeightFcn: @nav.algs.distanceEuclidean

Inspect the states table of the graph.

disp(navGraphObj.States)

          StateVector          Name     Lanes
    _______________________    _____    _____

    8          2    0.72176    {'A'}      2  
    1          1    0.29188    {'B'}      2  
    7          7    0.91777    {'C'}      2  
    8         10    0.71458    {'D'}      2  
    5          1    0.54254    {'E'}      2  
    3          6    0.14217    {'F'}      2  
    2          9    0.37334    {'G'}      3  
    8          7    0.67413    {'H'}      2  

Inspect the links table of the graph. The first column contains the indices of states from the states table. The two-element vectors in the first column of the table represent the pairs of states that are connected. Note that the links table also contains 'Weight' and 'Curvature' metadata in addition to the connected state pairs.

disp(navGraphObj.Links)

    EndStates    Weight    Curvature
    _________    ______    _________

     1    3      1.5089    0.0034635
     3    7       8.921    0.0063649
     5    4       2.387    0.0060558
     6    2      19.452    0.0041751
     7    1      38.776    0.0051347
     7    8      13.938    0.0076324
     8    2      43.893    0.0031493

Display the graph. From the graph, you can infer that the states 'D' and 'E' are not connected to any other states, and no path exists when a start or goal point lies on one of these states.

show(navGraphObj)

Add links between these state pairs:

• States with names "C" and "D".

• States with names "E" and "F".

• States with names "H" and "D"

In addition to the state pairs, you must also specify the values for associated Weight and Curvature metadata in the links table. The function returns the indices of the new state pairs in the links table.

Id = addlink(navGraphObj,["C" "D";"E" "F";"H" "D"],[5;2.5;50],[0.005;0.003;0.004])

Id = 3×1

     2
     5
    10

Inspect the updated links table for new state pairs and their associated metadata. Note that the state indices of the new state pairs are added to the second, fifth, and tenth rows of the links table. The entries in the links table are sorted according to the index of the first state in each state pair listed in the first column. The rows that have the same index for the first state are sorted based on the index of the second state in each state pair.

disp(navGraphObj.Links)

    EndStates    Weight    Curvature
    _________    ______    _________

     1    3      1.5089    0.0034635
     3    4           5        0.005
     3    7       8.921    0.0063649
     5    4       2.387    0.0060558
     5    6         2.5        0.003
     6    2      19.452    0.0041751
     7    1      38.776    0.0051347
     7    8      13.938    0.0076324
     8    2      43.893    0.0031493
     8    4          50        0.004

Display the updated graph.

show(navGraphObj)

Input Arguments

graph — Graph object

navGraph object

Graph object, specified as a navGraph object.

Data Types: double

statePairs — Indices or names of states to be linked

two-element column vector | M-by-2 matrix | cell array of strings

Indices or names of the states to be linked, specified as a two-element column vector, M-by-2 matrix, or a cell array of strings. The indices or names of the states to be linked must be taken from the states table of the input graph. M specifies the number of state pairs to be linked.

The values in the column vector or matrix can be

• Numeric data, specifying the indices of the states to be connected. For example, when you specify statePairs as [1 3], the function connects the states listed in the first and third rows of the states table of the input graph.

• String data, specifying the names of the states to be connected. For example, when you specify statePairs as ["A" "B"], the function fetches states with names "A" and "B" from the states table of the input graph and connects those two states.

Note

If the specified state pairs already exist in the links table of the input graph, the function will not add the duplicate pair to the graph.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | string | cell

metadata — Metadata containing additional information

numeric array | cell array of character vectors | string array | cell array of strings

Metadata containing additional information about the links connecting the states, specified as a numeric array, cell array of character vectors, string array, or cell array of strings.

Data Types: double | string | cell

Output Arguments

linkIDs — Link identifiers

column vector of positive integers

Link identifiers, returned as a column vector of positive integers. Link identifiers represent the indices of the state pairs added to the links table of the graph. The length of the vector specifies the number of new state pairs that are linked in the graph.

The addlink function sorts the rows of the links table in ascending order based on the index of the first state in each state pair listed in the first column of the table. If two or more rows have the same index for the first state, the function will then sort those rows according to the index of the second state in each state pair.

status — Status indicating if new links are added

M-element column vector

Since R2025a

Status indicating if new links are added, returned as an M-element column vector containing 0's and 1's. Each element indicates whether the corresponding link specified in the input argument statePairs is added to the graph (1 for added, 0 for not added). The size of this vector matches the number of state pairs specified in statePairs.

The function does not add links between the same state (self-links). If you specify a link between identical states, the function ignores it.

Data Types: logical

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

For code generation,

• Declare states variable in the States table of the navGraph object as a variable-size data, prior to constructing the table.

  coder.varsize("states")

• State names are not supported.

• Specify state pairs as numeric array.

Version History

Introduced in R2024a

R2025a: New output argument to indicate if new links are added

Starting in R2025a, the addlink function outputs a second argument states to indicate new state pair links specified in the input statePairs is added to the graph.