Three-tiered memory management (STM, WM, LTM) for RTAB-Map. More...

#include <Memory.h>

Collaboration diagram for rtabmap::Memory:

[legend]

Public Member Functions
	Memory (const ParametersMap &parameters=ParametersMap())
	Constructs a Memory instance with the given parameters.

virtual void	parseParameters (const ParametersMap &parameters)
	Re-parses parameters and propagates them to owned sub-objects.

virtual const ParametersMap &	getParameters () const

bool	update (const SensorData &data, Statistics *stats=0)
	Adds a sensor observation to the map (overload without odometry pose).

bool	update (const SensorData &data, const Transform &pose, const cv::Mat &covariance, const std::vector< float > &velocity=std::vector< float >(), Statistics *stats=0)
	Adds a sensor observation with odometry pose and velocity to the map.

bool	init (const std::string &dbUrl, bool dbOverwritten=false, const ParametersMap &parameters=ParametersMap(), bool postInitClosingEvents=false)
	Opens or creates a database and loads existing state into WM.

void	close (bool databaseSaved=true, bool postInitClosingEvents=false, const std::string &ouputDatabasePath="")
	Flushes pending data and closes the database connection.

std::map< int, float >	computeLikelihood (const Signature *signature, const std::list< int > &ids)
	Computes loop-closure likelihood of `signature` against a set of WM ids.

int	incrementMapId (std::map< int, int > *reducedIds=0)
	Starts a new map id, breaking session continuity (e.g. after localization loss).

void	updateAge (int signatureId)
	Refreshes the age of `signatureId` in working memory, marking it as recent.

std::list< int >	forget (const std::set< int > &ignoredIds=std::set< int >())
	Transfers oldest signatures from WM to LTM to respect memory and/or time limits.

std::set< int >	reactivateSignatures (const std::list< int > &ids, unsigned int maxLoaded, double &timeDbAccess)
	Reloads signatures from LTM into WM.

int	cleanup ()
	Drops the last signature if flagged as bad, or any signature in localization mode.

void	saveStatistics (const Statistics &statistics, bool saveWMState)
	Persists `statistics` to the database; `saveWMState` records the WM id list.

void	savePreviewImage (const cv::Mat &image) const
	Stores a preview image (typically a thumbnail of the last frame) in the database.

cv::Mat	loadPreviewImage () const
	Loads the preview image previously written by savePreviewImage().

void	saveOptimizedPoses (const std::map< int, Transform > &optimizedPoses, const Transform &lastlocalizationPose) const
	Persists an optimized pose graph and the last localization pose for next session.

std::map< int, Transform >	loadOptimizedPoses (Transform *lastlocalizationPose) const
	Loads optimized poses previously written by saveOptimizedPoses().

void	save2DMap (const cv::Mat &map, float xMin, float yMin, float cellSize) const
	Persists a 2D occupancy grid (origin `xMin`, `yMin` and resolution `cellSize`).

cv::Mat	load2DMap (float &xMin, float &yMin, float &cellSize) const
	Loads the 2D occupancy grid previously written by save2DMap().

void	saveOptimizedMesh (const cv::Mat &cloud, const std::vector< std::vector< std::vector< RTABMAP_PCL_INDEX > > > &polygons=std::vector< std::vector< std::vector< RTABMAP_PCL_INDEX > > >(), const std::vector< std::vector< Eigen::Vector2f > > &texCoords=std::vector< std::vector< Eigen::Vector2f > >(), const cv::Mat &textures=cv::Mat()) const
	Persists an optimized textured/colored mesh to the database.

cv::Mat	loadOptimizedMesh (std::vector< std::vector< std::vector< RTABMAP_PCL_INDEX > > > polygons=0, std::vector< std::vector< Eigen::Vector2f > > texCoords=0, cv::Mat *textures=0) const
	Loads the optimized mesh previously written by saveOptimizedMesh().

void	emptyTrash ()
	Forces the database driver to flush any queued signature/word saves.

void	joinTrashThread ()
	Blocks until the asynchronous database write thread has finished pending work.

bool	addLink (const Link &link, bool addInDatabase=false)
	Adds a graph link between two signatures.

void	updateLink (const Link &link, bool updateInDatabase=false)
	Replaces an existing link with `link` (same endpoints and type).

void	removeAllVirtualLinks ()
	Removes every virtual link in WM.

void	removeVirtualLinks (int signatureId)
	Removes virtual links attached to `signatureId`.

std::map< int, int >	getNeighborsId (int signatureId, int maxGraphDepth, int maxCheckedInDatabase=-1, bool incrementMarginOnLoop=false, bool ignoreLoopIds=false, bool ignoreIntermediateNodes=false, bool ignoreLocalSpaceLoopIds=false, const std::set< int > &nodesSet=std::set< int >(), double *dbAccessTime=0) const
	Breadth-first walk of the pose graph from `signatureId`.

std::map< int, float >	getNeighborsIdRadius (int signatureId, float radius, const std::map< int, Transform > &optimizedPoses, int maxGraphDepth) const
	Returns neighbor ids within a Euclidean radius using optimized poses.

void	convertToIntermediate (int locationId)
	Marks `locationId` as intermediate (weight = -1); excludes it from loop closure.

void	deleteLocation (int locationId, std::list< int > *deletedWords=0, bool keepLinkedInDb=false)
	Removes `locationId` from WM/STM and the database.

void	saveLocationData (int locationId)
	Forces `locationId` to be flushed to the database.

void	removeLink (int idA, int idB)
	Removes any link between `idA` and `idB` (both directions).

void	removeRawData (int id, bool image=true, bool scan=true, bool userData=true, bool occupancyGrid=true)
	Strips raw images, scan, user data and/or occupancy grid from `id` to save memory (RAM). This doesn't clear any compressed data.

int	reduceNode (int id, float maxDistance=0.0f, bool keepLinkedInDb=false, int direction=0)
	Merges `id` with a close neighbor (graph reduction).

void	setDummyDictionary (bool enabled)
	Enables a dummy visual word dictionary (no descriptors kept, word ids only).

const std::map< int, double > &	getWorkingMem () const

size_t	getWorkingMemSize (bool ignoreIntermediateNodes=false) const
	Returns the number of signatures in working memory, excluding the virtual place.

int	getWorkingMemIntermediateNodesCount () const

int	getStMemIntermediateNodesCount () const

const std::set< int > &	getStMem () const

int	getMaxStMemSize () const

std::multimap< int, Link >	getNeighborLinks (int signatureId, bool lookInDatabase=false) const
	Returns neighbor (sequential) links of `signatureId`; `lookInDatabase` also checks LTM.

std::multimap< int, Link >	getLoopClosureLinks (int signatureId, bool lookInDatabase=false) const
	Returns loop-closure links of `signatureId`; `lookInDatabase` also checks LTM.

std::multimap< int, Link >	getLinks (int signatureId, bool lookInDatabase=false, bool withLandmarks=false) const
	Returns all links of `signatureId` (neighbor, loop, prior, gravity, ...).

std::multimap< int, Link >	getAllLinks (bool lookInDatabase, bool ignoreNullLinks=true, bool withLandmarks=false) const
	Returns links of every signature; `ignoreNullLinks` drops empty placeholders.

bool	isBinDataKept () const

float	getSimilarityThreshold () const

std::map< int, int >	getWeights () const

int	getLastSignatureId () const

const Signature *	getLastWorkingSignature (bool ignoreIntermediateNodes) const
	Returns the most recent WM signature.

std::map< int, Link >	getNodesObservingLandmark (int landmarkId, bool lookInDatabase) const
	Returns all nodes observing landmark `landmarkId`, mapped to the observation link.

int	getSignatureIdByLabel (const std::string &label, bool lookInDatabase=true) const

bool	labelSignature (int id, const std::string &label)
	Assigns or removes a label on `id`.

const std::map< int, std::string > &	getAllLabels () const

const std::map< int, std::set< int > > &	getLandmarksIndex () const

bool	allNodesInWM () const

bool	setUserData (int id, const cv::Mat &data)
	Attaches user data to signature `id`, compressing it on the fly if needed.

int	getDatabaseMemoryUsed () const

std::string	getDatabaseVersion () const

std::string	getDatabaseUrl () const

double	getDbSavingTime () const

int	getMapId (int id, bool lookInDatabase=false) const

Transform	getOdomPose (int signatureId, bool lookInDatabase=false) const

Transform	getGroundTruthPose (int signatureId, bool lookInDatabase=false) const

const std::map< int, Transform > &	getGroundTruths () const

void	getGPS (int id, GPS &gps, Transform &offsetENU, bool lookInDatabase, int maxGraphDepth=0) const
	Returns a GPS fix for `id`, falling back to the nearest GPS-tagged neighbor.

bool	getNodeInfo (int signatureId, Transform &odomPose, int &mapId, int &weight, std::string &label, double &stamp, Transform &groundTruth, std::vector< float > &velocity, GPS &gps, EnvSensors &sensors, bool lookInDatabase=false) const
	Reads metadata of `signatureId` (no images/scan/words).

cv::Mat	getImageCompressed (int signatureId) const

SensorData	getNodeData (int locationId, bool images, bool scan, bool userData, bool occupancyGrid) const
	Loads sensor data of `locationId` from WM or LTM.

void	getNodeWordsAndGlobalDescriptors (int nodeId, std::multimap< int, int > &words, std::vector< cv::KeyPoint > &wordsKpts, std::vector< cv::Point3f > &words3, cv::Mat &wordsDescriptors, std::vector< GlobalDescriptor > &globalDescriptors) const
	Loads the visual words, 3D points and global descriptors stored with `nodeId`.

void	getNodeCalibration (int nodeId, std::vector< CameraModel > &models, std::vector< StereoCameraModel > &stereoModels) const
	Loads mono and/or stereo camera calibration stored with `nodeId`.

std::set< int >	getAllSignatureIds (bool ignoreChildren=true) const
	Returns all signature ids in WM, STM and LTM.

bool	memoryChanged () const
	Reports whether the in-memory map has been modified since the database was last loaded or reset. close() uses this flag to decide whether the database needs to be rewritten.

bool	isIncremental () const

bool	isReadOnly () const

bool	isLocalizationDataSaved () const

const Signature *	getSignature (int id) const

bool	isInSTM (int signatureId) const

bool	isInWM (int signatureId) const

bool	isInLTM (int signatureId) const

bool	isIDsGenerated () const

int	getLastGlobalLoopClosureId () const

const Feature2D *	getFeature2D () const

bool	isGraphReduced () const

const std::vector< double > &	getOdomMaxInf () const

bool	isOdomGravityUsed () const

void	dumpMemoryTree (const char *fileNameTree) const
	Writes a human-readable dump of WM/STM, links and weights to `fileNameTree`.

virtual void	dumpMemory (std::string directory) const
	Dumps every internal map (signatures, words, dictionary) to text files in `directory`.

virtual void	dumpSignatures (const char *fileNameSign, bool words3D) const
	Dumps signatures' word ids (and 3D positions if `words3D`) to `fileNameSign`.

void	dumpDictionary (const char fileNameRef, const char fileNameDesc) const
	Dumps the visual word dictionary: references to `fileNameRef`, descriptors to `fileNameDesc`.

unsigned long	getMemoryUsed () const

void	generateGraph (const std::string &fileName, const std::set< int > &ids=std::set< int >())
	Writes a Graphviz DOT file of the pose graph.

int	cleanupLocalGrids (const std::map< int, Transform > &poses, const cv::Mat &map, float xMin, float yMin, float cellSize, int cropRadius=1, bool filterScans=false)
	Removes spurious obstacle points from each node's local grid using a reference 2D map.

const VWDictionary *	getVWDictionary () const

void	getMetricConstraints (const std::set< int > &ids, std::map< int, Transform > &poses, std::multimap< int, Link > &links, bool lookInDatabase=false, bool landmarksAdded=false)
	Extracts a sub-graph (poses + links) for a set of node ids.

Transform	computeTransform (Signature &fromS, Signature &toS, Transform guess, RegistrationInfo *info=0, bool useKnownCorrespondencesIfPossible=false) const
	Computes the relative transform from `fromS` to `toS` using the registration pipeline.

Transform	computeTransform (int fromId, int toId, Transform guess, RegistrationInfo *info=0, bool useKnownCorrespondencesIfPossible=false)
	Convenience overload: loads signatures by id and forwards to the Signature variant.

Transform	computeIcpTransform (const Signature &fromS, const Signature &toS, Transform guess, RegistrationInfo *info=0) const
	Refines a transform using ICP alignment of laser scans only.

Transform	computeIcpTransformMulti (int newId, int oldId, const std::map< int, Transform > &poses, RegistrationInfo *info=0)
	ICP registration of one node against an assembled cloud from multiple neighbors.

Static Public Attributes
static const int	kIdStart
	First valid signature id assigned to a new signature (positive integer).

static const int	kIdVirtual
	Reserved id for the "virtual place" used by the Bayes filter (negative).

static const int	kIdInvalid
	Sentinel value indicating an invalid signature id (zero).

Protected Attributes
DBDriver *	_dbDriver
	Database driver owning the persistent storage (created by init()).

Detailed Description

Three-tiered memory management (STM, WM, LTM) for RTAB-Map.

Memory is the core map data structure used by Rtabmap. It stores observations as Signature nodes connected by Link edges and orchestrates their lifecycle across three tiers:

Short-Term Memory (STM): most recently added signatures, kept at a fixed size (see Parameters::kMemSTMSize()). Used to delay recently observed places before they become candidates for loop closure.
Working Memory (WM): signatures available for loop-closure likelihood computation in the current iteration. Older signatures are transferred from WM to LTM by forget() to bound iteration time.
Long-Term Memory (LTM): persisted in the database via DBDriver. Signatures can be brought back to WM with reactivateSignatures() when their neighbors still in WM are good loop-closure candidates.

The class also owns a visual word dictionary (VWDictionary), feature extractor (Feature2D) and registration pipelines (Registration, RegistrationVis, RegistrationIcp) used to compute relative transforms between signatures.

Typical iteration: update() adds a new SensorData as a Signature in STM; computeLikelihood() scores it against WM; the Rtabmap caller decides on loop closures with BayesFilter; cleanup() drops bad signatures; forget() transfers oldest WM signatures to LTM and reactivateSignatures() pulls relevant ones back.

See also: Signature; DBDriver; VWDictionary; Rtabmap

Definition at line 101 of file Memory.h.

Constructor & Destructor Documentation

◆ Memory()

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

Constructs a Memory instance with the given parameters.

The database is not opened here; call init() to open or create a database and load persisted state. parameters may include any key from Parameters (memory, keypoint, registration, etc.); missing keys fall back to defaults.

Member Function Documentation

◆ parseParameters()

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

virtual

Re-parses parameters and propagates them to owned sub-objects.

Forwards the relevant subset to VWDictionary, Feature2D, the registration pipelines and the database driver. Safe to call at runtime to change settings.

◆ getParameters()

virtual const ParametersMap & rtabmap::Memory::getParameters ( ) const

inlinevirtual

Returns: The most recent parameter map applied via the constructor or parseParameters().

Definition at line 130 of file Memory.h.

◆ update() [1/2]

bool rtabmap::Memory::update	(	const SensorData &	data,
		Statistics *	stats = `0`
	)

Adds a sensor observation to the map (overload without odometry pose).

Equivalent to calling the full update() with an identity pose and empty covariance. The new signature is added to STM; oldest STM entries are promoted to WM as needed.

Parameters

data	Sensor data (images, scan, user data, odometry features) for this frame.
stats	Optional output statistics receiver for timing/diagnostic values.

Returns: True if a signature was successfully created and added, false otherwise.

◆ update() [2/2]

bool rtabmap::Memory::update	(	const SensorData &	data,
		const Transform &	pose,
		const cv::Mat &	covariance,
		const std::vector< float > &	velocity = `std::vector< float >()`,
		Statistics *	stats = `0`
	)

Adds a sensor observation with odometry pose and velocity to the map.

Creates a new Signature, extracts visual words, links it to the previous STM signature with a neighbor link, runs rehearsal against STM and promotes the oldest STM signature to WM if STM is full.

Parameters

data	Sensor data (images, scan, user data, odometry features).
pose	Odometry pose at this frame (null if odometry not used).
covariance	6x6 odometry covariance (or empty if null odometry is provided).
velocity	Optional 6-vector (vx, vy, vz, vroll, vpitch, vyaw).
stats	Optional output statistics receiver.

Returns: True on success, false if signature creation failed.

◆ init()

bool rtabmap::Memory::init	(	const std::string &	dbUrl,
		bool	dbOverwritten = `false`,
		const ParametersMap &	parameters = `ParametersMap()`,
		bool	postInitClosingEvents = `false`
	)

Opens or creates a database and loads existing state into WM.

Parameters

dbUrl	Path to the database file (empty for in-memory).
dbOverwritten	If true, deletes the existing file before opening.
parameters	Optional parameter override applied before loading.
postInitClosingEvents	If true, posts RtabmapEventInit events for progress reporting (used by GUI).

Returns: True on success, false if the database could not be opened.

◆ close()

void rtabmap::Memory::close	(	bool	databaseSaved = `true`,
		bool	postInitClosingEvents = `false`,
		const std::string &	ouputDatabasePath = `""`
	)

Flushes pending data and closes the database connection.

Parameters

databaseSaved	If true, persists STM/WM signatures and statistics before closing. If false, in-memory state is discarded.
postInitClosingEvents	If true, posts progress events while closing.
ouputDatabasePath	If non-empty, the database is copied to this path on close. If a database on disk was initially created/loaded on a different path, it will be updated with latest changes and renamed to the output path.

◆ computeLikelihood()

std::map< int, float > rtabmap::Memory::computeLikelihood	(	const Signature *	signature,
		const std::list< int > &	ids
	)

Computes loop-closure likelihood of signature against a set of WM ids.

Compares visual words (tf-idf if enabled) between signature and each id in ids and returns a normalized likelihood per id.

Parameters

signature	Query signature (typically the last added one).
ids	Candidate signature ids in working memory.

Returns: Map from id to likelihood score.

◆ incrementMapId()

int rtabmap::Memory::incrementMapId ( std::map< int, int > * reducedIds = 0 )

Starts a new map id, breaking session continuity (e.g. after localization loss).

Parameters

reducedIds If non-null, populated with id remappings produced by graph reduction triggered by the new map.

Returns: The new map id (auto-incremented).

◆ updateAge()

void rtabmap::Memory::updateAge ( int signatureId )

Refreshes the age of signatureId in working memory, marking it as recent.

Used to keep loop-closure hypotheses active so they are not transferred to LTM during the next forget() call.

◆ forget()

std::list< int > rtabmap::Memory::forget ( const std::set< int > & ignoredIds = std::set< int >() )

Transfers oldest signatures from WM to LTM to respect memory and/or time limits.

Two regimes are used depending on the visual word dictionary state:

Word-count regime: active only when mapping mode is on, the VWDictionary is in incremental mode, contains at least one word, and is not using incremental FLANN. In this regime, signatures are transferred until the number of visual words removed from the dictionary catches up with the number of new words indexed since the previous iteration.
Signature-count regime: used in every other case (localization mode, dictionary not incremental, dictionary still empty – e.g. lidar-only mapping or no feature extraction – or incremental FLANN, where the word count is no longer the bottleneck). In this regime, at least one more signature than the count added/retrieved in the previous iteration is transferred, regardless of words.

In both regimes, candidate selection (see getRemovableSignatures()) honors ignoredIds, skips intermediate nodes, and excludes WM nodes linked to STM (to preserve rehearsal). Intermediate (weight==-1) nodes linked to a transferred signature are dragged out with it.

Parameters

ignoredIds Signatures that must not be transferred (e.g. STM, retrieved ids, on the planned path).

Returns: Ids of signatures moved to LTM, in transfer order.

◆ reactivateSignatures()

std::set< int > rtabmap::Memory::reactivateSignatures	(	const std::list< int > &	ids,
		unsigned int	maxLoaded,
		double &	timeDbAccess
	)

Reloads signatures from LTM into WM.

Parameters

ids	Candidate ids; those already in WM/STM are ignored.
maxLoaded	Hard cap on number of ids actually loaded (0 = unlimited).
timeDbAccess	Output: time spent in the database driver (seconds).

Returns: Ids effectively brought back to WM.

◆ cleanup()

int rtabmap::Memory::cleanup ( )

Drops the last signature if flagged as bad, or any signature in localization mode.

Returns: Id of the removed signature, or 0 if none was removed.

◆ saveOptimizedMesh()

void rtabmap::Memory::saveOptimizedMesh	(	const cv::Mat &	cloud,
		const std::vector< std::vector< std::vector< RTABMAP_PCL_INDEX > > > &	polygons = `std::vector< std::vector< std::vector< RTABMAP_PCL_INDEX > > >()`,
		const std::vector< std::vector< Eigen::Vector2f > > &	texCoords = `std::vector< std::vector< Eigen::Vector2f > >()`,
		const cv::Mat &	textures = `cv::Mat()`
	)		const

Persists an optimized textured/colored mesh to the database.

Parameters

cloud	Point cloud (XYZRGB) of vertices.
polygons	Per-texture list of polygons; each polygon is a list of vertex indices.
texCoords	Per-texture list of UV coords matching `polygons`.
textures	Concatenated texture images (square, equal-sized).

◆ addLink()

bool rtabmap::Memory::addLink	(	const Link &	link,
		bool	addInDatabase = `false`
	)

Adds a graph link between two signatures.

Parameters

link	Link to add (type, transform, covariance).
addInDatabase	If true, the link is also added when one of the ids is only in LTM.

Returns: True if the link was added, false on conflict or missing nodes.

◆ getNeighborsId()

std::map< int, int > rtabmap::Memory::getNeighborsId	(	int	signatureId,
		int	maxGraphDepth,
		int	maxCheckedInDatabase = `-1`,
		bool	incrementMarginOnLoop = `false`,
		bool	ignoreLoopIds = `false`,
		bool	ignoreIntermediateNodes = `false`,
		bool	ignoreLocalSpaceLoopIds = `false`,
		const std::set< int > &	nodesSet = `std::set< int >()`,
		double *	dbAccessTime = `0`
	)		const

Breadth-first walk of the pose graph from signatureId.

Visits neighbor and (optionally) loop-closure neighbors up to maxGraphDepth.

Parameters

signatureId	Starting node.
maxGraphDepth	Maximum graph distance (0 = infinite graph depth).
maxCheckedInDatabase	Cap on LTM look-ups (-1 = unlimited, 0 = WM only).
incrementMarginOnLoop	If true, loop-closure links count toward depth.
ignoreLoopIds	If true, loop-closure neighbors are not traversed.
ignoreIntermediateNodes	If true, weight==-1 intermediate nodes are skipped.
ignoreLocalSpaceLoopIds	If true, only global loop closures are traversed.
nodesSet	If non-empty, traversal is constrained to these ids.
dbAccessTime	Output: time spent in database access (seconds).

Returns: Map from visited node id to graph depth, including signatureId (with graph depth of 0)

◆ getNeighborsIdRadius()

std::map< int, float > rtabmap::Memory::getNeighborsIdRadius	(	int	signatureId,
		float	radius,
		const std::map< int, Transform > &	optimizedPoses,
		int	maxGraphDepth
	)		const

Returns neighbor ids within a Euclidean radius using optimized poses.

Parameters

signatureId	Query node id.
radius	Maximum distance from `signatureId` (meters).
optimizedPoses	Pose graph after optimization (used for distances).
maxGraphDepth	Maximum graph distance (in terms of nodes) to bound the search.

Returns: Map from node id to squared distance from signatureId.

◆ deleteLocation()

void rtabmap::Memory::deleteLocation	(	int	locationId,
		std::list< int > *	deletedWords = `0`,
		bool	keepLinkedInDb = `false`
	)

Removes locationId from WM/STM and the database.

Parameters

locationId	Id of the signature to delete.
deletedWords	Optional output: words whose reference count dropped to zero.
keepLinkedInDb	If true, the location keeps its links, weight and label and stays part of the graph in the database. If false (default), it is unlinked first – links removed on both sides, weight invalidated, label cleared – so at best it is kept as history only and no longer appears in getAllSignatureIds(). An unlinked location is written to the database only if it was already saved there or if Parameters::kMemNotLinkedNodesKept() is true (default); otherwise it is discarded outright.

◆ reduceNode()

int rtabmap::Memory::reduceNode	(	int	id,
		float	maxDistance = `0.0f`,
		bool	keepLinkedInDb = `false`,
		int	direction = `0`
	)

Merges id with a close neighbor (graph reduction).

Parameters

id	Node to reduce.
maxDistance	Maximum distance to a neighbor to allow the merge (meters).
keepLinkedInDb	Same meaning as in deleteLocation(): if true, the merged node keeps its links, weight and label and stays part of the graph in the database. If false (default), it is unlinked first – links removed on both sides, weight invalidated, label cleared – so at best it is kept as history only and no longer appears in getAllSignatureIds(). An unlinked node is written to the database only if it was already saved there or if Parameters::kMemNotLinkedNodesKept() is true (default); otherwise it is discarded outright.
direction	Restrict merge target: 0=any, 1=previous neighbor, 2=next neighbor.

Returns: Id of the node id was merged into, or 0 if no reduction was performed.

◆ setDummyDictionary()

void rtabmap::Memory::setDummyDictionary ( bool enabled )

Enables a dummy visual word dictionary (no descriptors kept, word ids only).

Note: Must be called before init(); ignored (with an error logged) once the database driver is set.; Silently disabled by init() when the database holds no dictionary, since there would be nothing to skip loading, and the memory would otherwise be left unable to add new nodes.

◆ getWorkingMem()

const std::map< int, double > & rtabmap::Memory::getWorkingMem ( ) const

inline

Returns: Working memory as { signature id, age } (does not include STM).

Definition at line 400 of file Memory.h.

◆ getWorkingMemSize()

size_t rtabmap::Memory::getWorkingMemSize ( bool ignoreIntermediateNodes = false ) const

Returns the number of signatures in working memory, excluding the virtual place.

Parameters

ignoreIntermediateNodes If true, intermediate nodes (weight = -1) are not counted.

◆ getWorkingMemIntermediateNodesCount()

int rtabmap::Memory::getWorkingMemIntermediateNodesCount ( ) const

inline

Returns: Number of intermediate nodes (weight = -1) currently in working memory.

Definition at line 407 of file Memory.h.

◆ getStMemIntermediateNodesCount()

int rtabmap::Memory::getStMemIntermediateNodesCount ( ) const

inline

Returns: Number of intermediate nodes (weight = -1) currently in short-term memory.

Definition at line 409 of file Memory.h.

◆ getStMem()

const std::set< int > & rtabmap::Memory::getStMem ( ) const

inline

Returns: Set of signature ids currently in short-term memory.

Definition at line 411 of file Memory.h.

◆ getMaxStMemSize()

int rtabmap::Memory::getMaxStMemSize ( ) const

inline

Returns: Configured maximum STM size (Parameters::kMemSTMSize()).

Definition at line 413 of file Memory.h.

◆ getLinks()

std::multimap< int, Link > rtabmap::Memory::getLinks	(	int	signatureId,
		bool	lookInDatabase = `false`,
		bool	withLandmarks = `false`
	)		const

Returns all links of signatureId (neighbor, loop, prior, gravity, ...).

Parameters

signatureId	Source node id (can also be a landmark id).
lookInDatabase	Also query LTM for links.
withLandmarks	Include landmark links in the result.

◆ isBinDataKept()

bool rtabmap::Memory::isBinDataKept ( ) const

inline

Returns: True if raw binary data (images, scans) is kept in memory after compression.

Definition at line 432 of file Memory.h.

◆ getSimilarityThreshold()

float rtabmap::Memory::getSimilarityThreshold ( ) const

inline

Returns: Similarity threshold used by rehearsal (Parameters::kMemRehearsalSimilarity()).

Definition at line 434 of file Memory.h.

◆ getWeights()

std::map< int, int > rtabmap::Memory::getWeights ( ) const

Returns: Map from signature id to weight (rehearsal accumulation count) for WM and STM.

◆ getLastSignatureId()

int rtabmap::Memory::getLastSignatureId ( ) const

Returns: Id of the most recently added signature, or 0 if none.

◆ getLastWorkingSignature()

const Signature * rtabmap::Memory::getLastWorkingSignature ( bool ignoreIntermediateNodes ) const

Returns the most recent WM signature.

Parameters

ignoreIntermediateNodes If true, skips weight==-1 placeholder nodes.

◆ getSignatureIdByLabel()

int rtabmap::Memory::getSignatureIdByLabel	(	const std::string &	label,
		bool	lookInDatabase = `true`
	)		const

Returns: Signature id labeled label, or 0 if not found.

◆ labelSignature()

bool rtabmap::Memory::labelSignature	(	int	id,
		const std::string &	label
	)

Assigns or removes a label on id.

Parameters

id	Signature id; pass 0 to remove an existing label by name.
label	Label text; empty to remove.

Returns: True if the label was applied.

◆ getAllLabels()

const std::map< int, std::string > & rtabmap::Memory::getAllLabels ( ) const

inline

Returns: Map from signature id to non-empty label (including STM+WM+LTM).

Definition at line 456 of file Memory.h.

◆ getLandmarksIndex()

const std::map< int, std::set< int > > & rtabmap::Memory::getLandmarksIndex ( ) const

inline

Returns: Reverse landmark index: { landmark id (negative), nodes observing it }.

Definition at line 458 of file Memory.h.

◆ allNodesInWM()

bool rtabmap::Memory::allNodesInWM ( ) const

inline

Returns: True if every persisted node (in LTM) is currently loaded in WM/STM.

Definition at line 460 of file Memory.h.

◆ setUserData()

bool rtabmap::Memory::setUserData	(	int	id,
		const cv::Mat &	data
	)

Attaches user data to signature id, compressing it on the fly if needed.

The format is detected automatically: a single-row CV_8UC1 matrix is treated as already-compressed data and stored as-is; anything else is considered raw and compressed before being stored.

Note: If you pass one-dimensional unsigned 8-bit raw data, transpose it so it has multiple rows (not multiple columns), otherwise it will be misdetected as already compressed.

Parameters

id	Target signature id (must be in WM/STM or LTM).
data	Raw or pre-compressed user data.

Returns: True if the data was attached, false if id was not found.

◆ getDatabaseMemoryUsed()

int rtabmap::Memory::getDatabaseMemoryUsed ( ) const

Returns: On-disk database size in bytes.

◆ getDatabaseVersion()

std::string rtabmap::Memory::getDatabaseVersion ( ) const

Returns: Schema version of the open database (e.g. "0.20.0").

◆ getDatabaseUrl()

std::string rtabmap::Memory::getDatabaseUrl ( ) const

Returns: File path of the open database (empty if in-memory).

◆ getDbSavingTime()

double rtabmap::Memory::getDbSavingTime ( ) const

Returns: Last emptyTrash() flush time in seconds.

◆ getMapId()

int rtabmap::Memory::getMapId	(	int	id,
		bool	lookInDatabase = `false`
	)		const

Returns: Map id of signature id; lookInDatabase also queries LTM.

◆ getOdomPose()

Transform rtabmap::Memory::getOdomPose	(	int	signatureId,
		bool	lookInDatabase = `false`
	)		const

Returns: Odometry pose stored with signatureId (null if unknown).

◆ getGroundTruthPose()

Transform rtabmap::Memory::getGroundTruthPose	(	int	signatureId,
		bool	lookInDatabase = `false`
	)		const

Returns: Ground-truth pose stored with signatureId (null if unknown).

◆ getGroundTruths()

const std::map< int, Transform > & rtabmap::Memory::getGroundTruths ( ) const

inline

Returns: Ground-truth poses for nodes currently in WM/STM.

Definition at line 493 of file Memory.h.

◆ getGPS()

void rtabmap::Memory::getGPS	(	int	id,
		GPS &	gps,
		Transform &	offsetENU,
		bool	lookInDatabase,
		int	maxGraphDepth = `0`
	)		const

Returns a GPS fix for id, falling back to the nearest GPS-tagged neighbor.

Two cases:

If id has a GPS fix attached, gps is set to that fix and offsetENU is left at identity.
Otherwise, the graph is searched (via getNeighborsId() with depth maxGraphDepth, ignoring loop closures) for the closest neighbor that has a GPS fix. When one is found, gps is set to that neighbor's fix and offsetENU is the rigid transform from that neighbor's pose to id, expressed in ENU coordinates (derived from the neighbor's heading/bearing). Applying offsetENU on top of the GPS-derived pose of the neighbor yields the ENU pose of id.

If no GPS fix is found on id or any reachable neighbor, gps is returned empty (gps.stamp()==0) and offsetENU is identity.

Parameters

id	Query signature id.
gps	Output GPS fix (empty if none found).
offsetENU	Output ENU-frame offset from the GPS-tagged node to `id` (identity when `id` itself carries the GPS fix or when none is found).
lookInDatabase	If true, also fetch missing nodes from LTM during the search.
maxGraphDepth	Maximum graph depth used to look for a GPS-tagged neighbor when `id` has none (0 = no depth limit, i.e. search the whole reachable graph).

◆ getNodeInfo()

bool rtabmap::Memory::getNodeInfo	(	int	signatureId,
		Transform &	odomPose,
		int &	mapId,
		int &	weight,
		std::string &	label,
		double &	stamp,
		Transform &	groundTruth,
		std::vector< float > &	velocity,
		GPS &	gps,
		EnvSensors &	sensors,
		bool	lookInDatabase = `false`
	)		const

Reads metadata of signatureId (no images/scan/words).

Parameters

signatureId	Node id.
odomPose	Output odometry pose (null if not set).
mapId	Output map id.
weight	Output rehearsal weight.
label	Output label (empty if none).
stamp	Output timestamp (seconds, epoch).
groundTruth	Output ground-truth pose (null if not set).
velocity	Output 6-vector velocity (empty if not set).
gps	Output GPS fix (invalid if not set).
sensors	Output environmental sensor readings.
lookInDatabase	Also query LTM.

Returns: True if signatureId was found.

◆ getImageCompressed()

cv::Mat rtabmap::Memory::getImageCompressed ( int signatureId ) const

Returns: Compressed image blob for signatureId (empty if not stored).

◆ getNodeData()

SensorData rtabmap::Memory::getNodeData	(	int	locationId,
		bool	images,
		bool	scan,
		bool	userData,
		bool	occupancyGrid
	)		const

Loads sensor data of locationId from WM or LTM.

Parameters

images	Include compressed RGB/depth images.
scan	Include laser scan blob.
userData	Include user data blob.
occupancyGrid	Include occupancy grid cells.

◆ getAllSignatureIds()

std::set< int > rtabmap::Memory::getAllSignatureIds ( bool ignoreChildren = true ) const

Returns all signature ids in WM, STM and LTM.

Parameters

ignoreChildren If true, nodes not linked to graph anymore are excluded

◆ memoryChanged()

bool rtabmap::Memory::memoryChanged ( ) const

inline

Reports whether the in-memory map has been modified since the database was last loaded or reset. close() uses this flag to decide whether the database needs to be rewritten.

The flag is cleared to false on construction, by close() and when the memory is cleared, and is raised to true on any of the following events:

update() in mapping mode (Parameters::kMemIncrementalMemory() == true, see isIncremental()): every successful call sets the flag, since a new Signature is added to the graph and the visual word dictionary may grow.
update() in localization mode (isIncremental() == false): the flag is set only when Parameters::kMemLocalizationDataSaved() is enabled (see isLocalizationDataSaved()), i.e. when the new node must be persisted back to the database. Pure localization (the default, Parameters::kMemLocalizationDataSaved() == false) leaves the flag at false even after many update() calls, because nothing needs to be saved.
reduceNode(): merging a node into a neighbor mutates the graph and marks the memory as changed (and also raises the link-changed flag).
init() dictionary repair: when init() rebuilds the visual word dictionary because words are missing from the database, the flag is forced to true so the regenerated dictionary is saved back on close(), even if no new data was processed.

Note that link-only modifications (e.g. addLink(), updateLink(), removeLink()) update an independent _linksChanged flag, not this one.

Returns: True if the memory has changed and would need to be persisted.

Definition at line 602 of file Memory.h.

◆ isIncremental()

bool rtabmap::Memory::isIncremental ( ) const

inline

Returns: True if the memory grows on update() (mapping mode), false in localization mode.

See also: Parameters::kMemIncrementalMemory()

Definition at line 607 of file Memory.h.

◆ isReadOnly()

bool rtabmap::Memory::isReadOnly ( ) const

inline

Returns: True in localization mode when database writes are disabled (i.e. isIncremental() is false and Parameters::kMemLocalizationReadOnly() is enabled).

See also: Parameters::kMemIncrementalMemory(); Parameters::kMemLocalizationReadOnly()

Definition at line 614 of file Memory.h.

◆ isLocalizationDataSaved()

bool rtabmap::Memory::isLocalizationDataSaved ( ) const

inline

Returns: True if data added during localization is persisted to the database.

See also: Parameters::kMemLocalizationDataSaved()

Definition at line 619 of file Memory.h.

◆ getSignature()

const Signature * rtabmap::Memory::getSignature ( int id ) const

Returns: Signature with id in WM/STM, or null if not loaded.

◆ isInSTM()

bool rtabmap::Memory::isInSTM ( int signatureId ) const

inline

Returns: True if signatureId is in short-term memory.

Definition at line 623 of file Memory.h.

◆ isInWM()

bool rtabmap::Memory::isInWM ( int signatureId ) const

inline

Returns: True if signatureId is in working memory.

Definition at line 625 of file Memory.h.

◆ isInLTM()

bool rtabmap::Memory::isInLTM ( int signatureId ) const

inline

Returns: True if signatureId is not in STM/WM, so when it is in LTM or non-existing.

Definition at line 627 of file Memory.h.

◆ isIDsGenerated()

bool rtabmap::Memory::isIDsGenerated ( ) const

inline

Returns: True if signature ids are auto-generated, false if taken from sensor data id.

Definition at line 629 of file Memory.h.

◆ getLastGlobalLoopClosureId()

int rtabmap::Memory::getLastGlobalLoopClosureId ( ) const

inline

Returns: Id of the last accepted global loop-closure node, or 0 if none.

Definition at line 631 of file Memory.h.

◆ getFeature2D()

const Feature2D * rtabmap::Memory::getFeature2D ( ) const

inline

Returns: Feature extractor used to compute visual words.

Definition at line 633 of file Memory.h.

◆ isGraphReduced()

bool rtabmap::Memory::isGraphReduced ( ) const

inline

Returns: True if graph reduction is enabled (Parameters::kMemReduceGraph()).

Definition at line 635 of file Memory.h.

◆ getOdomMaxInf()

const std::vector< double > & rtabmap::Memory::getOdomMaxInf ( ) const

inline

Returns: Running per-axis maximum of the diagonal of every neighbor (odometry) link's information matrix observed so far, as a 6-vector (x, y, z, roll, pitch, yaw). Empty until at least one 6x6 neighbor link information matrix has been seen.

This is a runtime statistic, not a configurable parameter: it is updated on init() (over all loaded neighbor links) and on every update() that adds a new neighbor link.

It is consumed by Rtabmap::getInformation() when Parameters::kRGBDLoopCovLimited() is enabled, to clip loop-closure information matrices so a loop never claims higher confidence than odometry itself ever provided.

See also: Parameters::kRGBDLoopCovLimited()

Definition at line 653 of file Memory.h.

◆ isOdomGravityUsed()

bool rtabmap::Memory::isOdomGravityUsed ( ) const

inline

Returns: True if the odometry pose orientation is used (instead of the IMU orientation) as the source of each new node's gravity link.

When enabled, every new node gets a self-loop Link::kGravity holding the rotation of the odometry pose passed to update(). This assumes odometry is already gravity-aligned (e.g. a VIO front-end). When disabled, the gravity link is built from the IMU orientation in SensorData::imu() if available.

Gravity links are consumed by graph optimization only when Parameters::kOptimizerGravitySigma() is non-zero.

See also: Parameters::kMemUseOdomGravity(); Parameters::kOptimizerGravitySigma()

Definition at line 669 of file Memory.h.

◆ getMemoryUsed()

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

Returns: Approximate RAM usage of the in-memory state, in bytes.

◆ generateGraph()

void rtabmap::Memory::generateGraph	(	const std::string &	fileName,
		const std::set< int > &	ids = `std::set< int >()`
	)

Writes a Graphviz DOT file of the pose graph.

Parameters

fileName	Output path.
ids	If non-empty, restrict the graph to these node ids.

◆ cleanupLocalGrids()

int rtabmap::Memory::cleanupLocalGrids	(	const std::map< int, Transform > &	poses,
		const cv::Mat &	map,
		float	xMin,
		float	yMin,
		float	cellSize,
		int	cropRadius = `1`,
		bool	filterScans = `false`
	)

Removes spurious obstacle points from each node's local grid using a reference 2D map.

For every node in poses, the node's local obstacle grid is loaded, each obstacle point is projected with poses into the reference map, and the point is kept only if either:

the reference map cell at its projection is not free space (i.e. the cell is an obstacle or unknown, value != 0), or
the reference map contains an obstacle cell (value == 100) within cropRadius cells of the projection.

Points that fall on a free cell and have no obstacle neighbor within cropRadius are dropped. The filtered obstacle grid replaces the node's grid in WM/STM and (if the node is already persisted) in the database via DBDriver::updateOccupancyGrid().

Ground and empty cells are not touched: they are read and written back as-is.

When filterScans is true, the same projection/filtering rule is also applied to each node's raw laser scan, and the rewritten scan is saved back to the database. This is useful to remove dynamic objects from the stored scans before re-meshing or re-exporting.

Parameters

poses	Optimized poses used to project the local grids/scans into `map`.
map	Reference 2D occupancy grid (cell values: 0 free, 100 occupied, anything else unknown).
xMin	Reference map origin x in world coordinates (meters).
yMin	Reference map origin y in world coordinates (meters).
cellSize	Reference map resolution (meters/cell); must match the nodes' grid cell size.
cropRadius	Search radius (in cells) around each projected point used to accept points near an obstacle in `map`.
filterScans	If true, also filter and rewrite the raw laser scan attached to each node, using the same rule as for obstacle cells.

Returns: Number of (node, grid or scan) modifications performed, or -1 on error (no database loaded, empty poses or empty map).

◆ getVWDictionary()

const VWDictionary * rtabmap::Memory::getVWDictionary ( ) const

Returns: Visual word dictionary used for tf-idf likelihood and feature matching.

◆ getMetricConstraints()

void rtabmap::Memory::getMetricConstraints	(	const std::set< int > &	ids,
		std::map< int, Transform > &	poses,
		std::multimap< int, Link > &	links,
		bool	lookInDatabase = `false`,
		bool	landmarksAdded = `false`
	)

Extracts a sub-graph (poses + links) for a set of node ids.

Used by graph optimization callers to retrieve constraints for a region of interest.

Parameters

ids	Ids to include.
poses	Output: odometry poses for `ids`.
links	Output: links between the nodes (and to landmarks if `landmarksAdded`).
lookInDatabase	If true, fetch missing data from LTM.
landmarksAdded	If true, also include landmark constraints.

◆ computeTransform()

Transform rtabmap::Memory::computeTransform	(	Signature &	fromS,
		Signature &	toS,
		Transform	guess,
		RegistrationInfo *	info = `0`,
		bool	useKnownCorrespondencesIfPossible = `false`
	)		const

Computes the relative transform from fromS to toS using the registration pipeline.

Parameters

fromS	Source signature (will be modified to cache extracted data).
toS	Target signature.
guess	Initial transform estimate (null if unknown).
info	Optional output with inlier counts, variance and diagnostics.
useKnownCorrespondencesIfPossible	If true, reuses existing word-id correspondences.

Returns: The estimated transform, or a null Transform on failure.

◆ computeIcpTransform()

Transform rtabmap::Memory::computeIcpTransform	(	const Signature &	fromS,
		const Signature &	toS,
		Transform	guess,
		RegistrationInfo *	info = `0`
	)		const

Refines a transform using ICP alignment of laser scans only.

Returns: The refined transform, or a null Transform on failure.

◆ computeIcpTransformMulti()

Transform rtabmap::Memory::computeIcpTransformMulti	(	int	newId,
		int	oldId,
		const std::map< int, Transform > &	poses,
		RegistrationInfo *	info = `0`
	)

ICP registration of one node against an assembled cloud from multiple neighbors.

Parameters

newId	New (query) node id.
oldId	Reference node id.
poses	Neighbor poses used to assemble the reference cloud.
info	Optional output with inlier counts and diagnostics.

Returns: The estimated transform, or a null Transform on failure.

Member Data Documentation

◆ kIdStart

const int rtabmap::Memory::kIdStart

static

First valid signature id assigned to a new signature (positive integer).

Definition at line 105 of file Memory.h.

◆ kIdVirtual

const int rtabmap::Memory::kIdVirtual

static

Reserved id for the "virtual place" used by the Bayes filter (negative).

Definition at line 107 of file Memory.h.

◆ kIdInvalid

const int rtabmap::Memory::kIdInvalid

static

Sentinel value indicating an invalid signature id (zero).

Definition at line 109 of file Memory.h.

◆ _dbDriver

DBDriver* rtabmap::Memory::_dbDriver

protected

Database driver owning the persistent storage (created by init()).

Definition at line 819 of file Memory.h.

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

corelib/include/rtabmap/core/Memory.h

Public Member Functions

Static Public Attributes

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Memory()

Member Function Documentation

◆ parseParameters()

◆ getParameters()

◆ update() [1/2]

◆ update() [2/2]

◆ init()

◆ close()

◆ computeLikelihood()

◆ incrementMapId()

◆ updateAge()

◆ forget()

◆ reactivateSignatures()

◆ cleanup()

◆ saveOptimizedMesh()

◆ addLink()

◆ getNeighborsId()

◆ getNeighborsIdRadius()

◆ deleteLocation()

◆ reduceNode()

◆ setDummyDictionary()

◆ getWorkingMem()

◆ getWorkingMemSize()

◆ getWorkingMemIntermediateNodesCount()

◆ getStMemIntermediateNodesCount()

◆ getStMem()

◆ getMaxStMemSize()

◆ getLinks()

◆ isBinDataKept()

◆ getSimilarityThreshold()

◆ getWeights()

◆ getLastSignatureId()

◆ getLastWorkingSignature()

◆ getSignatureIdByLabel()

◆ labelSignature()

◆ getAllLabels()

◆ getLandmarksIndex()

◆ allNodesInWM()

◆ setUserData()

◆ getDatabaseMemoryUsed()

◆ getDatabaseVersion()

◆ getDatabaseUrl()

◆ getDbSavingTime()

◆ getMapId()

◆ getOdomPose()

◆ getGroundTruthPose()

◆ getGroundTruths()

◆ getGPS()

◆ getNodeInfo()

◆ getImageCompressed()

◆ getNodeData()

◆ getAllSignatureIds()

◆ memoryChanged()

◆ isIncremental()

◆ isReadOnly()

◆ isLocalizationDataSaved()

◆ getSignature()

◆ isInSTM()

◆ isInWM()

◆ isInLTM()

◆ isIDsGenerated()

◆ getLastGlobalLoopClosureId()

◆ getFeature2D()

◆ isGraphReduced()

◆ getOdomMaxInf()

◆ isOdomGravityUsed()

◆ getMemoryUsed()

◆ generateGraph()

◆ cleanupLocalGrids()

◆ getVWDictionary()

◆ getMetricConstraints()

◆ computeTransform()

◆ computeIcpTransform()

◆ computeIcpTransformMulti()

Member Data Documentation