hasNewKeyFrame

Check if new key frame added in stereo visual SLAM object

Since R2025a

collapse all in page

    Syntax

    hasAdded = hasNewKeyFrame(vslam)

    Description

    hasAdded = hasNewKeyFrame(vslam) returns a logical value that indicates if a new key frame has been added within the stereo visual simultaneous localization and mapping (vSLAM) object vslam.

    example

    Examples

    collapse all

    Open Live Script

    Perform stereo visual simultaneous localization and mapping (vSLAM) using the data from the UTIAS Long-Term Localization and Mapping Dataset provided by University of Toronto Institute for Aerospace Studies. You can download the data to a directory using a web browser, or by running this code:

    ftpObj = ftp("asrl3.utias.utoronto.ca");
tempFolder = fullfile(tempdir);
dataFolder = [tempFolder,'2020-vtr-dataset\UTIAS-In-The-Dark\'];
zipFileName = [dataFolder,'run_000005.zip'];
folderExists = exist(dataFolder,"dir");

    Create a folder in a temporary directory to save the downloaded file and extract its contents.

    if ~folderExists  
    mkdir(dataFolder) 
    disp("Downloading run_000005.zip (818 MB). This download can take a few minutes.") 
    mget(ftpObj,"/2020-vtr-dataset/UTIAS-In-The-Dark/run_000005.zip",tempFolder);

    disp("Extracting run_000005.zip (818 MB) ...") 
    unzip(zipFileName,dataFolder); 
end

    Create two imageDatastore objects to store the stereo images.

    imgFolderLeft = [dataFolder,'\images\left\'];
imgFolderRight = [dataFolder,'\images\right\'];
imdsLeft = imageDatastore(imgFolderLeft);
imdsRight = imageDatastore(imgFolderRight);

    Specify the intrinsic parameters and the baseline of the stereo camera, and use them to create a stereo visual SLAM object. The focal length, principal point, and image size is in pixels, and the baseline is in meters.

    focalLength = [387.777 387.777];  
principalPoint = [257.446 197.718];  
imageSize = [384 512];            
intrinsics = cameraIntrinsics(focalLength,principalPoint,imageSize);
baseline = 0.239965; 

vslam = stereovslam(intrinsics,baseline,MaxNumPoints=600, ...
    TrackFeatureRange=[30 120],SkipMaxFrames=5);

    Process each pair of stereo images and visualize the camera poses and 3-D map points.

    for i = 1:numel(imdsLeft.Files)
    leftImage = readimage(imdsLeft,i);
    rightImage = readimage(imdsRight,i);
    addFrame(vslam,leftImage,rightImage);

    if hasNewKeyFrame(vslam)
        % Query 3-D map points and camera poses
        xyzPoints = mapPoints(vslam);
        [camPoses,viewIds] = poses(vslam);

        % Display 3-D map points and camera trajectory
        plot(vslam);
    end

    % Get current status of system
    status = checkStatus(vslam);
    
    % Stop adding frames when tracking is lost
    if status == uint8(0)
        break
    end
end

    Once all the frames have been processed, reset the system.

    while ~isDone(vslam)
    plot(vslam)
end

    Figure contains an axes object. The axes object with xlabel X, ylabel Y contains 12 objects of type line, text, patch, scatter. This object represents Camera trajectory.

    reset(vslam)

    Input Arguments

    collapse all

    Stereo visual SLAM object, specified as a stereovslam object.

    Output Arguments

    collapse all

    New key frame status, returned as a logical 0 (false) or 1 (true). A value of true indicates that a new key frame has been added within the stereo visual SLAM object vslam. A value of false indicates that no new key frame has been added. The object considers an image frame to be a key frame if the number of tracked feature points in the current frame satisfies one these conditions:

    • The number of tracked feature points is within the limits specified by the TrackFeatureRange property of the stereovslam object vslam.

    • The number of tracked feature points is greater than the upper limit specified by the TrackFeatureRange property of the stereovslam object vslam, and the number of skipped frames since adding the last key frame equals the value of the SkipMaxFrames property of vslam.

    The hasNewKeyFrame object function returns true only when the stereovslam object has added one or more new key frames since the last hasNewKeyFrame call. For example, if the stereovslam object adds only one key frame, then two consecutive calls to hasNewKeyFrame return true and false, respectively.

    Version History

    Introduced in R2025a

    See Also

    Objects

    Functions