Manages a dictionary of visual words for visual place recognition and loop closure detection. More...

#include <VWDictionary.h>

Public Types
enum	NNStrategy { kNNFlannNaive , kNNFlannKdTree , kNNFlannLSH , kNNBruteForce , kNNBruteForceGPU , kNNUndef }
	Nearest neighbor search strategies for descriptor matching. More...

Public Member Functions
	VWDictionary (const ParametersMap &parameters=ParametersMap())
	Constructor.

virtual	~VWDictionary ()
	Destructor.

virtual void	parseParameters (const ParametersMap &parameters)
	Parse and apply parameters from a parameters map.

virtual void	update ()
	Update the search index with newly added words.

virtual std::list< int >	addNewWords (const cv::Mat &descriptors, int signatureId)
	Add new visual words from descriptors.

virtual void	addWord (VisualWord *vw)
	Add an existing visual word to the dictionary.

std::vector< int >	findNN (const std::list< VisualWord * > &vws) const
	Find nearest neighbor visual word IDs for a list of visual words.

std::vector< int >	findNN (const cv::Mat &descriptors) const
	Find nearest neighbor visual word IDs for descriptors.

bool	addWordRef (int wordId, int signatureId)
	Add a reference from a visual word to a signature.

void	removeAllWordRef (int wordId, int signatureId)
	Remove all references from a visual word to a signature.

const VisualWord *	getWord (int id) const
	Get a visual word by ID.

VisualWord *	getUnusedWord (int id) const
	Get an unused visual word by ID.

void	setLastWordId (int id)
	Set the last word ID (used when loading from database)

const std::map< int, VisualWord * > &	getVisualWords () const
	Get all visual words.

float	getNndrRatio () const
	Get the Nearest Neighbor Distance Ratio (NNDR) threshold.

unsigned int	getNotIndexedWordsCount () const
	Get the count of words not yet indexed in the search tree.

int	getLastIndexedWordId () const
	Get the ID of the last indexed word.

int	getTotalActiveReferences () const
	Get the total number of active word-to-signature references.

unsigned int	getIndexedWordsCount () const
	Get the count of words currently indexed in the search tree.

unsigned int	getIndexMemoryUsed () const
	Get the memory used by the search index.

unsigned long	getMemoryUsed () const
	Get the total memory used by the dictionary.

bool	setNNStrategy (NNStrategy strategy)
	Set the nearest neighbor search strategy.

NNStrategy	getNNStrategy () const
	Get the current nearest neighbor search strategy.

bool	isIncremental () const
	Check if the dictionary is in incremental mode.

bool	isIncrementalFlann () const
	Check if FLANN index is updated incrementally.

void	setIncrementalDictionary ()
	Set the dictionary to incremental mode.

void	setFixedDictionary (const std::string &dictionaryPath)
	Set the dictionary to fixed mode and load from file.

bool	isModified () const
	Check if the dictionary has been modified since last save.

void	rebuildIndex ()

std::vector< unsigned char >	serializeIndex () const
	Serialize the search index to a byte vector.

bool	deserializeIndex (const std::vector< unsigned char > &data)
	Deserialize the search index from a byte vector.

bool	deserializeIndex (const unsigned char *data, size_t size)
	Deserialize the search index from raw bytes.

void	exportDictionary (const char fileNameReferences, const char fileNameDescriptors) const
	Export the dictionary to files.

void	clear (bool printWarningsIfNotEmpty=true)
	Clear all visual words and reset the dictionary.

std::vector< VisualWord * >	getUnusedWords () const
	Get all unused visual words.

std::vector< int >	getUnusedWordIds () const
	Get IDs of all unused visual words.

unsigned int	getUnusedWordsSize () const
	Get the count of unused visual words.

void	removeWords (const std::vector< VisualWord * > &words)
	Remove words from the dictionary.

void	deleteUnusedWords ()
	Delete all unused visual words.

Static Public Member Functions
static std::string	nnStrategyName (NNStrategy strategy)
	Get the name of a nearest neighbor strategy.

static cv::Mat	convertBinTo32F (const cv::Mat &descriptorsIn, bool byteToFloat=true)
	Convert binary descriptors to 32-bit float format.

static cv::Mat	convert32FToBin (const cv::Mat &descriptorsIn, bool byteToFloat=true)
	Convert 32-bit float descriptors to binary format.

Static Public Attributes
static const int	ID_START
	Starting ID for visual words (typically 1)

static const int	ID_INVALID
	Invalid visual word ID (typically 0)

Protected Member Functions
int	getNextId ()
	Get the next available visual word ID.

Protected Attributes
std::map< int, VisualWord * >	_visualWords
	Map of visual word ID to VisualWord pointer.

int	_totalActiveReferences
	Total count of active word-to-signature references.

Detailed Description

Manages a dictionary of visual words for visual place recognition and loop closure detection.

The VWDictionary class maintains a collection of visual words (feature descriptors) and provides efficient nearest neighbor search capabilities. It supports both incremental and fixed dictionary modes:

Incremental mode: New visual words are added dynamically as new images are processed
Fixed mode: A pre-computed dictionary is loaded from a file

The class uses various nearest neighbor search strategies (FLANN, brute force, GPU-accelerated) to match descriptors efficiently. It tracks word references to signatures (images) and manages unused words for memory optimization.

Note: Visual words are identified by unique integer IDs starting from VWDictionary::ID_START

Definition at line 65 of file VWDictionary.h.

Member Enumeration Documentation

◆ NNStrategy

enum rtabmap::VWDictionary::NNStrategy

Nearest neighbor search strategies for descriptor matching.

Enumerator
kNNFlannNaive	FLANN naive search (exhaustive)
kNNFlannKdTree	FLANN kd-tree index (fast for high-dimensional descriptors)
kNNFlannLSH	FLANN Locality-Sensitive Hashing (ideal for binary descriptors)
kNNBruteForce	Brute force CPU search.
kNNBruteForceGPU	Brute force GPU-accelerated search (requires CUDA)
kNNUndef	Undefined strategy.

Definition at line 72 of file VWDictionary.h.

Constructor & Destructor Documentation

◆ VWDictionary()

rtabmap::VWDictionary::VWDictionary ( const ParametersMap & parameters = ParametersMap() )

Constructor.

Parameters

parameters Optional parameters map to configure the dictionary

◆ ~VWDictionary()

virtual rtabmap::VWDictionary::~VWDictionary ( )

virtual

Destructor.

Clears all visual words and releases resources.

Member Function Documentation

◆ nnStrategyName()

static std::string rtabmap::VWDictionary::nnStrategyName ( NNStrategy strategy )

inlinestatic

Get the name of a nearest neighbor strategy.

Parameters

strategy The strategy enum value

Returns: String representation of the strategy name

Definition at line 96 of file VWDictionary.h.

◆ parseParameters()

virtual void rtabmap::VWDictionary::parseParameters ( const ParametersMap & parameters )

virtual

Parse and apply parameters from a parameters map.

Parameters

parameters Parameters map containing configuration values

◆ update()

virtual void rtabmap::VWDictionary::update ( )

virtual

Update the search index with newly added words.

This method rebuilds the nearest neighbor search index (FLANN, etc.) to include any words that were added but not yet indexed.

◆ addNewWords()

virtual std::list< int > rtabmap::VWDictionary::addNewWords	(	const cv::Mat &	descriptors,
		int	signatureId
	)

virtual

Add new visual words from descriptors.

Parameters

descriptors	Matrix of descriptors (one row per descriptor)
signatureId	ID of the signature (image) these descriptors belong to

Returns: List of visual word IDs that were added or matched

For each descriptor, either matches it to an existing visual word (using nearest neighbor search with NNDR ratio) or creates a new visual word.

Note: If the dictionary is not incremental (fixed), NNDR is not applied and the closest existing visual word ID is always returned. If the dictionary is incremental, a new visual word is created if NNDR validation passes; otherwise, a reference to an existing visual word is added.

◆ addWord()

virtual void rtabmap::VWDictionary::addWord ( VisualWord * vw )

virtual

Add an existing visual word to the dictionary.

Parameters

vw	Pointer to the visual word to add (ownership is transferred)

Note: The dictionary takes ownership of the VisualWord object

◆ findNN() [1/2]

std::vector< int > rtabmap::VWDictionary::findNN ( const std::list< VisualWord * > & vws ) const

Find nearest neighbor visual word IDs for a list of visual words.

Parameters

vws	List of visual words to match

Returns: Vector of visual word IDs (one per input visual word)

Note: If the dictionary is not incremental (fixed), NNDR is not applied and the closest visual word ID is always returned. If the dictionary is incremental, a valid visual word ID is returned only if NNDR validation passes.

◆ findNN() [2/2]

std::vector< int > rtabmap::VWDictionary::findNN ( const cv::Mat & descriptors ) const

Find nearest neighbor visual word IDs for descriptors.

Parameters

descriptors Matrix of descriptors (one row per descriptor)

Returns: Vector of visual word IDs (one per descriptor)

Note: If the dictionary is not incremental (fixed), NNDR is not applied and the closest visual word ID is always returned. If the dictionary is incremental, a valid visual word ID is returned only if NNDR validation passes.

◆ addWordRef()

bool rtabmap::VWDictionary::addWordRef	(	int	wordId,
		int	signatureId
	)

Add a reference from a visual word to a signature.

Parameters

wordId	ID of the visual word
signatureId	ID of the signature (image)

Returns: true if the word exists in the dictionary and the reference has been added, false otherwise

Tracks which signatures use which visual words. If the word was unused, it is removed from the unused words list.

◆ removeAllWordRef()

void rtabmap::VWDictionary::removeAllWordRef	(	int	wordId,
		int	signatureId
	)

Remove all references from a visual word to a signature.

Parameters

wordId	ID of the visual word
signatureId	ID of the signature (image)

If the word has no more references after this operation, it is added to the unused words list.

◆ getWord()

const VisualWord * rtabmap::VWDictionary::getWord ( int id ) const

Get a visual word by ID.

Parameters

id	Visual word ID

Returns: Pointer to the visual word, or nullptr if not found

◆ getUnusedWord()

VisualWord * rtabmap::VWDictionary::getUnusedWord ( int id ) const

Get an unused visual word by ID.

Parameters

id	Visual word ID

Returns: Pointer to the unused visual word, or nullptr if not found or not unused

Note: Ownership of the returned visual word still belongs to the dictionary. To transfer ownership to the caller, removeWords() must be called on this word.

◆ setLastWordId()

void rtabmap::VWDictionary::setLastWordId ( int id )

inline

Set the last word ID (used when loading from database)

Parameters

id	Last word ID

Definition at line 232 of file VWDictionary.h.

◆ getVisualWords()

const std::map< int, VisualWord * > & rtabmap::VWDictionary::getVisualWords ( ) const

inline

Get all visual words.

Returns: Map of visual word ID to VisualWord pointer

Definition at line 238 of file VWDictionary.h.

◆ getNndrRatio()

float rtabmap::VWDictionary::getNndrRatio ( ) const

inline

Get the Nearest Neighbor Distance Ratio (NNDR) threshold.

Returns: NNDR ratio value

The NNDR ratio is used to determine if a descriptor matches an existing visual word. If the ratio of distances to the first and second nearest neighbors is below this threshold, a match is accepted.

Note: The NNDR method was introduced in "Distinctive Image Features from Scale-Invariant Keypoints" by David Lowe (IJCV 2004).

Definition at line 251 of file VWDictionary.h.

◆ getNotIndexedWordsCount()

unsigned int rtabmap::VWDictionary::getNotIndexedWordsCount ( ) const

inline

Get the count of words not yet indexed in the search tree.

Returns: Number of words waiting to be indexed

Definition at line 257 of file VWDictionary.h.

◆ getLastIndexedWordId()

int rtabmap::VWDictionary::getLastIndexedWordId ( ) const

Get the ID of the last indexed word.

Returns: Last indexed word ID, or 0 if no words are indexed

◆ getTotalActiveReferences()

int rtabmap::VWDictionary::getTotalActiveReferences ( ) const

inline

Get the total number of active word-to-signature references.

Returns: Total count of active references

Definition at line 269 of file VWDictionary.h.

◆ getIndexedWordsCount()

unsigned int rtabmap::VWDictionary::getIndexedWordsCount ( ) const

Get the count of words currently indexed in the search tree.

Returns: Number of indexed words

◆ getIndexMemoryUsed()

unsigned int rtabmap::VWDictionary::getIndexMemoryUsed ( ) const

Get the memory used by the search index.

Returns: Memory usage in kilobytes

◆ getMemoryUsed()

unsigned long rtabmap::VWDictionary::getMemoryUsed ( ) const

Get the total memory used by the dictionary.

Returns: Memory usage in bytes

◆ setNNStrategy()

bool rtabmap::VWDictionary::setNNStrategy ( NNStrategy strategy )

Set the nearest neighbor search strategy.

Parameters

strategy The strategy to use

Returns: true if the search tree was re-initialized (strategy changed), false otherwise

Changing the strategy will rebuild the search index if words are already indexed.

◆ getNNStrategy()

NNStrategy rtabmap::VWDictionary::getNNStrategy ( ) const

inline

Get the current nearest neighbor search strategy.

Returns: The current NNStrategy

Definition at line 302 of file VWDictionary.h.

◆ isIncremental()

bool rtabmap::VWDictionary::isIncremental ( ) const

inline

Check if the dictionary is in incremental mode.

Returns: true if incremental, false if fixed

Definition at line 308 of file VWDictionary.h.

◆ isIncrementalFlann()

bool rtabmap::VWDictionary::isIncrementalFlann ( ) const

inline

Check if FLANN index is updated incrementally.

Returns: true if incremental FLANN updates are enabled

Definition at line 314 of file VWDictionary.h.

◆ setIncrementalDictionary()

void rtabmap::VWDictionary::setIncrementalDictionary ( )

Set the dictionary to incremental mode.

In incremental mode, new visual words can be added dynamically. This cannot be called if a fixed dictionary is already loaded.

◆ setFixedDictionary()

void rtabmap::VWDictionary::setFixedDictionary ( const std::string & dictionaryPath )

Set the dictionary to fixed mode and load from file.

Parameters

dictionaryPath Path to the dictionary file (.txt or .db format)

Loads a pre-computed dictionary from a file. The dictionary file format in txt format should be: one line per visual word, with word ID followed by descriptor values. This cannot be called if words are already in the dictionary.

◆ isModified()

bool rtabmap::VWDictionary::isModified ( ) const

Check if the dictionary has been modified since last save.

Returns: true if modified, false otherwise

◆ serializeIndex()

std::vector< unsigned char > rtabmap::VWDictionary::serializeIndex ( ) const

Serialize the search index to a byte vector.

Returns: Serialized index data

◆ deserializeIndex() [1/2]

bool rtabmap::VWDictionary::deserializeIndex ( const std::vector< unsigned char > & data )

Deserialize the search index from a byte vector.

Parameters

data	Serialized index data

Returns: true if deserialization was successful, false otherwise

◆ deserializeIndex() [2/2]

bool rtabmap::VWDictionary::deserializeIndex	(	const unsigned char *	data,
		size_t	size
	)

Deserialize the search index from raw bytes.

Parameters

data	Pointer to serialized index data
size	Size of the data in bytes

Returns: true if deserialization was successful, false otherwise

◆ exportDictionary()

void rtabmap::VWDictionary::exportDictionary	(	const char *	fileNameReferences,
		const char *	fileNameDescriptors
	)		const

Export the dictionary to files.

Parameters

fileNameReferences	Path to file for word-to-signature references
fileNameDescriptors	Path to file for visual word descriptors

Exports the dictionary in a format that can be loaded later.

◆ clear()

void rtabmap::VWDictionary::clear ( bool printWarningsIfNotEmpty = true )

Clear all visual words and reset the dictionary.

Parameters

printWarningsIfNotEmpty If true, print warnings if dictionary is not empty

Deletes all visual words and releases all resources.

◆ getUnusedWords()

std::vector< VisualWord * > rtabmap::VWDictionary::getUnusedWords ( ) const

Get all unused visual words.

Returns: Vector of pointers to unused visual words

Unused words are visual words that have no references to any signatures.

Note: Ownership of the returned visual words still belongs to the dictionary. To transfer ownership to the caller, removeWords() must be called on these words.

◆ getUnusedWordIds()

std::vector< int > rtabmap::VWDictionary::getUnusedWordIds ( ) const

Get IDs of all unused visual words.

Returns: Vector of unused word IDs

◆ getUnusedWordsSize()

unsigned int rtabmap::VWDictionary::getUnusedWordsSize ( ) const

inline

Get the count of unused visual words.

Returns: Number of unused words

Definition at line 404 of file VWDictionary.h.

◆ removeWords()

void rtabmap::VWDictionary::removeWords ( const std::vector< VisualWord * > & words )

Remove words from the dictionary.

Parameters

words Vector of visual word pointers to remove

Note: The caller is responsible for deleting the VisualWord objects

◆ deleteUnusedWords()

void rtabmap::VWDictionary::deleteUnusedWords ( )

Delete all unused visual words.

Removes and deletes visual words that have no references to any signatures.

◆ convertBinTo32F()

static cv::Mat rtabmap::VWDictionary::convertBinTo32F	(	const cv::Mat &	descriptorsIn,
		bool	byteToFloat = `true`
	)

static

Convert binary descriptors to 32-bit float format.

Parameters

descriptorsIn Input descriptors (CV_8UC1 for binary, or CV_32FC1 for float)

byteToFloat

Conversion mode:

If true: Simple type conversion from CV_8UC1 to CV_32FC1 using OpenCV's convertTo(). Each byte value becomes a float value (output dimensions unchanged).
If false: Bit-by-bit expansion for binary descriptors (e.g., ORB, BRIEF). Each input byte (8 bits) is expanded into 8 float values (0.0f or 1.0f), one per bit. Output has 8x the number of columns (e.g., 32 bytes -> 256 floats).

Returns: Descriptors in 32-bit float format (CV_32FC1)

◆ convert32FToBin()

static cv::Mat rtabmap::VWDictionary::convert32FToBin	(	const cv::Mat &	descriptorsIn,
		bool	byteToFloat = `true`
	)

static

Convert 32-bit float descriptors to binary format.

Parameters

descriptorsIn Input descriptors (CV_32FC1)

byteToFloat

Conversion mode:

If true: Simple type conversion from CV_32FC1 to CV_8UC1 using OpenCV's convertTo(). Each float value becomes a byte value (output dimensions unchanged).
If false: Bit-by-bit packing for binary descriptors. Each group of 8 float values (0.0f or 1.0f) is packed into 1 byte (8 bits), one bit per float. Input must have columns divisible by 8. Output has 1/8 the number of columns (e.g., 256 floats -> 32 bytes).

Returns: Descriptors in binary format (CV_8UC1)

◆ getNextId()

int rtabmap::VWDictionary::getNextId ( )

protected

Get the next available visual word ID.

Returns: Next unique word ID

Member Data Documentation

◆ ID_START

const int rtabmap::VWDictionary::ID_START

static

Starting ID for visual words (typically 1)

Definition at line 84 of file VWDictionary.h.

◆ ID_INVALID

const int rtabmap::VWDictionary::ID_INVALID

static

Invalid visual word ID (typically 0)

Definition at line 89 of file VWDictionary.h.

◆ _visualWords

std::map<int, VisualWord *> rtabmap::VWDictionary::_visualWords

protected

Map of visual word ID to VisualWord pointer.

Note: All visual words (used and unused) are stored here

Definition at line 461 of file VWDictionary.h.

◆ _totalActiveReferences

int rtabmap::VWDictionary::_totalActiveReferences

protected

Total count of active word-to-signature references.

Note: Used to track all references for updating common signatures

Definition at line 467 of file VWDictionary.h.

The documentation for this class was generated from the following file:

corelib/include/rtabmap/core/VWDictionary.h

Public Types

Public Member Functions

Static Public Member Functions

Static Public Attributes

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ NNStrategy

Constructor & Destructor Documentation

◆ VWDictionary()

◆ ~VWDictionary()

Member Function Documentation

◆ nnStrategyName()

◆ parseParameters()

◆ update()

◆ addNewWords()

◆ addWord()

◆ findNN() [1/2]

◆ findNN() [2/2]

◆ addWordRef()

◆ removeAllWordRef()

◆ getWord()

◆ getUnusedWord()

◆ setLastWordId()

◆ getVisualWords()

◆ getNndrRatio()

◆ getNotIndexedWordsCount()

◆ getLastIndexedWordId()

◆ getTotalActiveReferences()

◆ getIndexedWordsCount()

◆ getIndexMemoryUsed()

◆ getMemoryUsed()

◆ setNNStrategy()

◆ getNNStrategy()

◆ isIncremental()

◆ isIncrementalFlann()

◆ setIncrementalDictionary()

◆ setFixedDictionary()

◆ isModified()

◆ serializeIndex()

◆ deserializeIndex() [1/2]

◆ deserializeIndex() [2/2]

◆ exportDictionary()

◆ clear()

◆ getUnusedWords()

◆ getUnusedWordIds()

◆ getUnusedWordsSize()

◆ removeWords()

◆ deleteUnusedWords()

◆ convertBinTo32F()

◆ convert32FToBin()

◆ getNextId()

Member Data Documentation

◆ ID_START

◆ ID_INVALID

◆ _visualWords

◆ _totalActiveReferences