changeFilePaths

Change file paths in ground truth data

Syntax

unresolvedPaths = changeFilePaths(gTruth,alternativePaths)

[unresolvedPaths,unresolvedFolderPaths] = changeFilePaths(gTruth,alternativePaths)

Description

unresolvedPaths = changeFilePaths(gTruth,alternativePaths) changes the file paths stored in a groundTruth object, gTruth, based on pairs of current paths and alternative paths, alternativePaths. If gTruth is a vector of groundTruth objects, the function changes the file paths across all objects. The function returns the unresolved paths in unresolvedPaths. An unresolved path is any current path in alternativePaths not found in gTruth or any alternative path in alternativePaths not found at the specified path location. In both cases, unresolvedPaths returns only the current paths.

Use this function to update the file paths of ground truth data that changes folder locations. You can change file paths for the ground truth data source and pixel label data.

[unresolvedPaths,unresolvedFolderPaths] = changeFilePaths(gTruth,alternativePaths) additionally returns unresolved folder paths unresolvedFolderPaths, which lists the folder locations corresponding to the unresolved current paths returned in unresolvedPaths. Use unresolvedFolderPaths to identify unresolved paths at the folder level when unresolvedPaths contains many files from the same folder. (since R2026a)

Examples

Change File Paths in Ground Truth Data

Change the file paths to the data source and pixel label data in a groundTruth object.

Load a groundTruth object containing ground truth data into the workspace. The data source and pixel label data of the object contains file paths corresponding to an image sequence showing a building. MATLAB® displays a warning that the path to the data source cannot be found.

load('gTruthSeq.mat');

Warning: The data source points to a directory that cannot be found.
'C:\CFP\building'
Update the DataSource using <a href="matlab:doc('changeFilePaths')">changeFilePaths</a> method.

Display the current path to the data source.

gTruth.DataSource

ans = 
'C:\CFP\building'

Specify the current path to the data source and an alternative path and store these paths in a cell array. Use the changeFilePaths function to update the data source path based on the paths in the cell array. Because the function does not find the pixel label data at the specified new path, it returns the current unresolved paths.

currentPathDataSource = "C:\CFP\building";
newPathDataSource = fullfile(matlabroot,"toolbox\vision\visiondata\building");
alternativePaths = {[currentPathDataSource newPathDataSource]};
unresolvedPaths = changeFilePaths(gTruth,alternativePaths)

unresolvedPaths = 5×1 string array
    "C:\CFP\building\PixelLabelData\Label_1.png"
    "C:\CFP\building\PixelLabelData\Label_2.png"
    "C:\CFP\building\PixelLabelData\Label_3.png"
    "C:\CFP\building\PixelLabelData\Label_4.png"
    "C:\CFP\building\PixelLabelData\Label_5.png"

Verify that the paths in the groundTruth object match the unresolved paths returned by the changeFilePaths function. The unresolved paths are stored in the LabelData property of the groundTruth object, in the PixelLabelData column.

gTruth.LabelData.PixelLabelData

ans = 5×1 cell array
    "'C:\CFP\building\PixelLabelData\Label_1.png'"
    "'C:\CFP\building\PixelLabelData\Label_2.png'"
    "'C:\CFP\building\PixelLabelData\Label_3.png'"
    "'C:\CFP\building\PixelLabelData\Label_4.png'"
    "'C:\CFP\building\PixelLabelData\Label_5.png'"

Specify the current path and an alternative path for the pixel label files and change the file paths. The function updates the paths for all pixel labels. Because the function resolves all paths, it returns an empty array of unresolved paths.

currentPathPixels = "C:\CFP\building\PixelLabelData";
newPathPixels = fullfile(matlabroot,"toolbox\vision\visiondata\buildingPixellabels");
alternativePaths = {[currentPathPixels newPathPixels]};
unresolvedPaths = changeFilePaths(gTruth,alternativePaths)

unresolvedPaths = 

  0×0 empty string array

To view the new data source path, use the gTruth.DataSource command. To view the new pixel label data paths, use the gTruth.LabelData.PixelLabelData command.

Input Arguments

gTruth — Ground truth data

groundTruth object | array of groundTruth objects

Ground truth data, specified as a groundTruth object or array of groundTruth objects. You can export these objects from the Ground Truth Labeler (Automated Driving Toolbox) app or create them programmatically.

alternativePaths — Alternative file paths

1-by-2 string vector | cell array of 1-by-2 string vectors

Alternative file paths, specified as a 1-by-2 string vector or cell array of 1-by-2 string vectors of the form [p_current p_new].

• p_current is a current file path in gTruth. This file path can be from the data source or pixel label data of gTruth. Specify p_current using backslashes as the path separators.

• p_new is the new path to which you want to change p_current. Specify p_new using either forward slashes or backslashes as the path separators.

You can specify alternatives paths to these files:

• Data source — This path is stored in the DataSource property of gTruth. If you use changeFilePaths to update the DataSource property of a groundTruth object, the new path must already exist; otherwise, the path won’t update and the old value remains. Only after the file exists at the new location will the DataSource property update to reflect the new path and data type.

• Pixel label data — These paths are stored in the PixelLabelData column of the LabelData property of gTruth.

If gTruth is a vector of groundTruth objects, the function changes the file paths across all objects.

Example: ["C:\Pixels\PixelLabelData_1" "C:\Pixels\PixelLabelData_2] changes the path to the pixel label data folder. The function updates the path in all pixel label files stored in that folder.

Example: {["C:\Pixels\PixelLabelData_1" "C:\Pixels\PixelLabelData_2]; ["B:\Sources\video.mp4" "C:\Sources\video.mp4"]} changes the path to the pixel label data folder and the drive letter in the path to the data source.

Output Arguments

unresolvedPaths — Unresolved file paths

string array

Unresolved file paths, returned as a string array. If the function cannot find either the current path or new path in the string vectors specified by alternativePaths, then it returns the unresolved current paths in unresolvedPaths.

If the function finds and resolves all file paths, then it returns unresolvedPaths as an empty string array.

unresolvedFolderPaths — Unresolved folder paths

string array

Since R2026a

Unresolved folder paths, returned as a string array. This value lists the folder locations for the unresolved current paths returned in unresolvedPaths, providing a shorter list when many unresolved files come from the same folder.

If the function finds and resolves all file paths, then it returns unresolvedFolderPaths as an empty string array.

Version History

Introduced in R2018b

R2026a: Additional output argument unresolvedFolderPaths

The function can now also return an unresolvedFolderPaths output, which lists the folder locations for the unresolved file paths.