Overview
The KeyFrame class represents a carefully selected subset of frames that form the core of the map in ORB-SLAM3. KeyFrames store features, pose, covisibility relationships, and serve as nodes in the covisibility graph and spanning tree. They are essential for local mapping, loop closure, and bundle adjustment.
namespace ORB_SLAM3 {
class KeyFrame;
}
KeyFrame.h:52
Key Features
- Selected based on specific criteria to ensure good map coverage
- Connected through covisibility graph based on shared MapPoint observations
- Organized in spanning tree structure for efficient map management
- Support loop closure detection and map merging
- Store Bag-of-Words representation for place recognition
- IMU preintegration data for visual-inertial SLAM
Constructor
KeyFrame(Frame &F, Map* pMap, KeyFrameDatabase* pKFDB);
F - Source framepMap - Map to which this KeyFrame belongspKFDB - KeyFrame database for place recognition
KeyFrames are created during tracking when certain criteria are met: sufficient time has passed, tracking quality is good, or enough new MapPoints are visible.
Pose Functions
SetPose
void SetPose(const Sophus::SE3f &Tcw);
GetPose
Returns the camera pose with thread safety.
GetPoseInverse
Sophus::SE3f GetPoseInverse();
GetCameraCenter
Eigen::Vector3f GetCameraCenter();
GetRotation / GetTranslation
Eigen::Matrix3f GetRotation();
Eigen::Vector3f GetTranslation();
Covisibility Graph
The covisibility graph connects KeyFrames that observe common MapPoints, enabling efficient local mapping and optimization.
AddConnection
void AddConnection(KeyFrame* pKF, const int &weight);
EraseConnection
void EraseConnection(KeyFrame* pKF);
UpdateConnections
void UpdateConnections(bool upParent=true);
GetConnectedKeyFrames
std::set<KeyFrame*> GetConnectedKeyFrames();
GetBestCovisibilityKeyFrames
std::vector<KeyFrame*> GetBestCovisibilityKeyFrames(const int &N);
GetCovisiblesByWeight
std::vector<KeyFrame*> GetCovisiblesByWeight(const int &w);
GetWeight
int GetWeight(KeyFrame* pKF);
Spanning Tree
KeyFrames are organized in a spanning tree to enable efficient propagation of updates during optimization.
AddChild / EraseChild
void AddChild(KeyFrame* pKF);
void EraseChild(KeyFrame* pKF);
ChangeParent
void ChangeParent(KeyFrame* pKF);
GetParent / GetChilds
KeyFrame* GetParent();
std::set<KeyFrame*> GetChilds();
hasChild
bool hasChild(KeyFrame* pKF);
Loop Closure
AddLoopEdge
void AddLoopEdge(KeyFrame* pKF);
GetLoopEdges
std::set<KeyFrame*> GetLoopEdges();
Map Merging
AddMergeEdge
void AddMergeEdge(KeyFrame* pKF);
GetMergeEdges
set<KeyFrame*> GetMergeEdges();
MapPoint Observations
AddMapPoint
void AddMapPoint(MapPoint* pMP, const size_t &idx);
EraseMapPointMatch
void EraseMapPointMatch(const int &idx);
void EraseMapPointMatch(MapPoint* pMP);
ReplaceMapPointMatch
void ReplaceMapPointMatch(const int &idx, MapPoint* pMP);
GetMapPoints
std::set<MapPoint*> GetMapPoints();
GetMapPointMatches
std::vector<MapPoint*> GetMapPointMatches();
TrackedMapPoints
int TrackedMapPoints(const int &minObs);
GetNumberMPs
Returns the total number of MapPoints observed.
Bag of Words
ComputeBoW
Computes the Bag of Words representation for place recognition.
Bad Flag Management
SetBadFlag
Marks the KeyFrame as bad and removes it from the map. Updates covisibility graph and spanning tree.
isBad
Returns true if the KeyFrame is marked as bad.
SetNotErase / SetErase
void SetNotErase();
void SetErase();
Data Members
Identification
static long unsigned int nNextId;
long unsigned int mnId; // KeyFrame unique ID
const long unsigned int mnFrameId; // Original frame ID
const double mTimeStamp; // Timestamp
Feature Data
// Number of keypoints
const int N;
// Keypoints and descriptors
const std::vector<cv::KeyPoint> mvKeys;
const std::vector<cv::KeyPoint> mvKeysUn;
const std::vector<float> mvuRight; // Stereo correspondence
const std::vector<float> mvDepth; // Depth information
const cv::Mat mDescriptors;
Bag of Words
DBoW2::BowVector mBowVec;
DBoW2::FeatureVector mFeatVec;
ORBVocabulary* mpORBvocabulary;
KeyFrameDatabase* mpKeyFrameDB;
Camera Calibration
const float fx, fy, cx, cy;
const float invfx, invfy;
const float mbf; // Baseline * fx
const float mb; // Baseline
const float mThDepth; // Close/far point threshold
cv::Mat mDistCoef;
Pose
// Camera pose (protected by mutex)
Sophus::SE3<float> mTcw; // World to camera
Eigen::Matrix3f mRcw;
Sophus::SE3<float> mTwc; // Camera to world
Eigen::Matrix3f mRwc;
IMU Data
bool bImu; // IMU availability flag
IMU::Bias mImuBias;
IMU::Calib mImuCalib;
IMU::Preintegrated* mpImuPreintegrated;
// IMU position and velocity
Eigen::Vector3f mOwb;
Eigen::Vector3f mVw;
bool mbHasVelocity;
// Previous/next KeyFrame in temporal sequence
KeyFrame* mPrevKF;
KeyFrame* mNextKF;
Covisibility Graph
// Connected KeyFrames with weights
std::map<KeyFrame*,int> mConnectedKeyFrameWeights;
std::vector<KeyFrame*> mvpOrderedConnectedKeyFrames;
std::vector<int> mvOrderedWeights;
Spanning Tree
bool mbFirstConnection;
KeyFrame* mpParent;
std::set<KeyFrame*> mspChildrens;
Loop Closure
std::set<KeyFrame*> mspLoopEdges;
std::set<KeyFrame*> mspMergeEdges;
// Loop closure variables
Sophus::SE3f mTcwGBA; // Pose after global BA
Sophus::SE3f mTcwBefGBA; // Pose before global BA
Eigen::Vector3f mVwbGBA;
Eigen::Vector3f mVwbBefGBA;
IMU::Bias mBiasGBA;
Map Association
Map* mpMap;
unsigned int mnOriginMapId;
Grid for Feature Matching
const int mnGridCols;
const int mnGridRows;
const float mfGridElementWidthInv;
const float mfGridElementHeightInv;
std::vector<std::vector<std::vector<size_t>>> mGrid;
ORB Scale Pyramid
const int mnScaleLevels;
const float mfScaleFactor;
const float mfLogScaleFactor;
const std::vector<float> mvScaleFactors;
const std::vector<float> mvLevelSigma2;
const std::vector<float> mvInvLevelSigma2;
Thread Safety
KeyFrame uses mutexes for thread-safe access:
std::mutex mMutexPose; // Pose, velocity, biases
std::mutex mMutexConnections; // Covisibility graph
std::mutex mMutexFeatures; // Features and MapPoints
std::mutex mMutexMap; // Map pointer
Usage Example
// Create KeyFrame from frame
KeyFrame* pKF = new KeyFrame(currentFrame, pMap, pKFDB);
// Compute BoW for place recognition
pKF->ComputeBoW();
// Update covisibility connections
pKF->UpdateConnections();
// Get best covisible KeyFrames
vector<KeyFrame*> vpNeighKFs = pKF->GetBestCovisibilityKeyFrames(10);
// Check covisibility weight
int weight = pKF->GetWeight(vpNeighKFs[0]);
// Get observed MapPoints
set<MapPoint*> spMapPoints = pKF->GetMapPoints();
KeyFrame selection is critical for system performance. Too few KeyFrames result in poor map coverage, while too many increase computational cost.
