RelocalizationStack Class Reference

#include <RGBD/Include/ImFusion/RGBD/RelocalizationStack.h>

RelocalizationStack coordinates multiple relocalization strategies to robustly estimate camera poses from RGBD images. More...

Inheritance diagram for RelocalizationStack:

Detailed Description

RelocalizationStack coordinates multiple relocalization strategies to robustly estimate camera poses from RGBD images.

This class is intended for scenarios where pose estimation reliability is increased by combining several relocalization algorithms.

The stack manages the lifetime of all contained relocalization instances (ownership is transferred on setRelocalizations). It supports two modes: either returning the first successful pose candidate or aggregating all candidates from all relocalizations. This design allows flexible integration of different relocalization approaches and easy switching between strategies.

All methods are not thread-safe unless otherwise stated.

Usage example:

// Setup stack with relocalization methods
std::vector<std::unique_ptr<Relocalization>> relocs;
relocs.push_back(std::make_unique<MyRelocMethod>());
relocs.push_back(std::make_unique<AnotherRelocMethod>());
RelocalizationStack stack;
stack.setRelocalizations(relocs);
stack.init(widthDepth, heightDepth, widthColor, heightColor);
 
// Add frames (ownership of images remains with caller)
stack.addFrame(id, imgDepth, imgColor, pose);
 
// Localize new frame
std::vector<std::tuple<mat4, double, int>> candidates;
stack.localize(imgDepth, imgColor, candidates, k);

Important aspects:

• Ownership of relocalization instances is transferred to the stack; do not use them elsewhere after calling setRelocalizations.
• Input images (imgDepth, imgColor) must remain valid for the duration of the method call; their ownership is not transferred.
• All input images must have compatible resolution and calibration.
• Error handling is via return codes; no exceptions are thrown.
• Not thread-safe.
• The stack is intended for use as a central relocalization manager in RGBD pipelines.

See also

Relocalization

Public Types
enum class	PoseCandidateMode { UseFirstSuccessfulRelocalization , UseAll }
	Specifies how pose candidates are selected from the stack. More...

Public Member Functions
void	clear () override
	Removes all frames and resets all contained relocalization databases.
bool	init (int widthDepth, int heightDepth, int widthColor, int heightColor) override
	Initializes all contained relocalizations with image dimensions.
int	addFrame (int id, TypedImage< float > *imgDepth, TypedImage< unsigned char > *imgColor, const mat4 &T, bool *addedToDatabase=0) override
	Adds a frame to all contained relocalization databases.
int	localize (TypedImage< float > *imgDepth, TypedImage< unsigned char > *imgColor, std::vector< std::tuple< mat4, double, int > > &T, int k=4) override
	Estimates pose candidates for a given frame using all contained relocalization methods.
void	setPoseCandidateMode (PoseCandidateMode mode)
	Sets the mode for pose candidate selection.
void	setRelocalizations (std::vector< std::unique_ptr< Relocalization > > &reloc)
	Transfers ownership of relocalization instances to the stack.
std::vector< Relocalization * >	relocalizations () const
	Returns raw pointers to the managed relocalization instances.
Public Member Functions inherited from Relocalization
	Relocalization ()
	Constructs the relocalization interface.
virtual	~Relocalization ()
	Destroys the relocalization interface.

Additional Inherited Members
Protected Member Functions inherited from NotCopyable
	NotCopyable (NotCopyable &&) noexcept=default
NotCopyable &	operator= (NotCopyable &&) noexcept=default
	NotCopyable (const NotCopyable &)=delete
NotCopyable &	operator= (const NotCopyable &)=delete

Member Enumeration Documentation

PoseCandidateMode

enum class PoseCandidateMode

strong

Specifies how pose candidates are selected from the stack.

Enumerator
UseFirstSuccessfulRelocalization	Only the first successful relocalization is used.
UseAll	All pose candidates from all relocalizations are aggregated.

Member Function Documentation

clear()

void clear ( )

overridevirtual

Removes all frames and resets all contained relocalization databases.

Implements Relocalization.

init()

bool init ( int widthDepth, int heightDepth, int widthColor, int heightColor )

overridevirtual

Initializes all contained relocalizations with image dimensions.

Must be called before adding frames or localizing.

Parameters

widthDepth	Width of input depth images (pixels).
heightDepth	Height of input depth images (pixels).
widthColor	Width of input color images (pixels).
heightColor	Height of input color images (pixels).

Returns

True if all relocalizations were successfully initialized. False otherwise.

Implements Relocalization.

addFrame()

int addFrame ( int id, TypedImage< float > * imgDepth, TypedImage< unsigned char > * imgColor, const mat4 & T, bool * addedToDatabase = 0 )

overridevirtual

Adds a frame to all contained relocalization databases.

The images must remain valid for the duration of the call; ownership is not transferred.

Parameters

	id	Frame identifier.
	imgDepth	Pointer to depth image.
	imgColor	Pointer to color image.
	T	Pose for the frame (4x4 matrix, world coordinates).
[out]	addedToDatabase	True if the frame was added to the pose database, false otherwise.

Returns

Zero if successful.

Implements Relocalization.

localize()

int localize ( TypedImage< float > * imgDepth, TypedImage< unsigned char > * imgColor, std::vector< std::tuple< mat4, double, int > > & T, int k = 4 )

overridevirtual

Estimates pose candidates for a given frame using all contained relocalization methods.

The images must remain valid for the duration of the call; ownership is not transferred.

Parameters

	imgDepth	Pointer to depth image (pixels in world units).
	imgColor	Pointer to color image (pixels in RGB).
[out]	T	Vector of pose candidates as tuples (pose matrix, normalized quality score [0..1], frame id).
	k	Maximum number of poses to return per relocalization.

Returns

Zero if successful.

Implements Relocalization.

setPoseCandidateMode()

void setPoseCandidateMode

(

PoseCandidateMode

mode

)

Sets the mode for pose candidate selection.

Parameters

mode	Selection mode (first successful or all).

setRelocalizations()

void setRelocalizations

(

std::vector< std::unique_ptr< Relocalization > > &

reloc

)

Transfers ownership of relocalization instances to the stack.

Parameters

reloc

Vector of unique pointers to Relocalization instances.

relocalizations()

std::vector< Relocalization * > relocalizations

(

)

const

Returns raw pointers to the managed relocalization instances.

The returned pointers are valid as long as the stack exists.

---

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

• RGBD/Include/ImFusion/RGBD/RelocalizationStack.h