This class provides unidirectional feature correspondences. More...

#include <UnidirectionalCorrespondences.h>

Public Types
using	CorrespondencePair = std::pair< unsigned int, unsigned int >
	Definition of a pair holding the indices of two corresponding features or descriptors.

using	CorrespondencePairs = std::vector< CorrespondencePair >
	Definition of a vector holding correspondence pairs.

Public Member Functions
	UnidirectionalCorrespondences (const size_t numberForward, const size_t numberBackward)
	Creates a new unidirectional correspondences object.

template<bool tThreadSafe>
void	addCandidate (const unsigned int forwardIndex, const unsigned int backwardIndex)
	Adds a new feature correspondence candidate.

CorrespondencePairs	correspondences () const
	Returns all unidirectional feature correspondences.

Static Public Member Functions
template<typename TDescriptor , typename TDistance , TDistance(*)(const TDescriptor &, const TDescriptor &) tDistanceFunction>
static CorrespondencePairs	determineCorrespondingDescriptors (const TDescriptor forwardDescriptors, const size_t numberForwardDescriptors, const TDescriptor backwardDescriptors, const size_t numberBackwardDescriptors, const TDistance maximalDistance, Worker *worker)
	Determines unidirectional correspondences pairs between two sets of descriptors.

template<typename TDescriptor , typename TDistance , TDistance(*)(const TDescriptor &, const TDescriptor &) tDistanceFunction>
static CorrespondencePairs	determineCorrespondingFeatures (const AnyCamera &camera, const HomogenousMatrix4 &world_T_camera, const Vector3 objectPoints, const TDescriptor objectPointDescriptors, const size_t numberObjectFeatures, const Vector2 imagePoints, const TDescriptor imagePointDescriptors, const size_t numberImageFeatures, const TDistance maximalDistance, const Scalar maximalProjectionError)
	Determines guided unidirectional correspondence pairs between image features and object features.

template<typename TFirst , typename TSecond >
static void	extractCorrespondenceElements (const CorrespondencePairs &correspondencePairs, const TFirst firstElements, const size_t sizeFirstElements, const TSecond secondElements, const size_t sizeSecondElements, std::vector< TFirst > &correspondenceFirstElements, std::vector< TSecond > &correspondenceSecondElements)
	Extracts corresponding elements based on correspondence pairs.

static size_t	countBijectiveCorrespondences (const Index32 *usedPointIndices, const size_t size)
	Counts the number of bijective correspondences based on provided indices of used points (either image points or object points).

static size_t	countNonBijectiveCorrespondences (const Index32 *usedPointIndices, const size_t size)
	Counts the number of non-bijective correspondences based on provided indices of used points (either image points or object points).

static void	removeNonBijectiveCorrespondences (const AnyCamera &camera, const HomogenousMatrix4 &world_T_camera, const Vector3 objectPoints, const Vector2 imagePoints, Indices32 &objectPointIndices, Indices32 &imagePointIndices, const bool checkImagePoints)
	Removes non-bijective correspondences from 2D/3D correspondences.

Static Protected Member Functions
template<typename TDescriptor , typename TDistance , TDistance(*)(const TDescriptor &, const TDescriptor &) tDistanceFunction, unsigned int tLocks>
static void	determineCorrespondingDescriptorsSubset (const TDescriptor forwardDescriptors, const size_t numberForwardDescriptors, const TDescriptor backwardDescriptors, const size_t numberBackwardDescriptors, const TDistance maximalDistance, Index32 forwardIndicesForBackwardDescriptors, Lock locks, const unsigned int subsetFirstForwardDescriptor, const unsigned int subsetNumberForwardDescriptors)
	Determines a subset of all unidirectional correspondences pairs between two sets of descriptors.

Protected Attributes
Indices32	forwardCounters_
	Correspondence counter for forward features (or for the first features).

Indices32	backwardCounters_
	Correspondence counter for backward features (or for the second features).

CorrespondencePairs	candidates_
	Correspondence candidates.

Lock	lock_
	The object's lock.

Static Protected Attributes
static constexpr Index32	matchCountZero_ = Index32(-1)
	Definition of a match count value for zero matches.

static constexpr Index32	matchCounterTwo_ = Index32(-2)
	Definition of a match count value for two+ matches.

Detailed Description

This class provides unidirectional feature correspondences.

Member Typedef Documentation

◆ CorrespondencePair

using Ocean::Tracking::UnidirectionalCorrespondences::CorrespondencePair = std::pair<unsigned int, unsigned int>

Definition of a pair holding the indices of two corresponding features or descriptors.

◆ CorrespondencePairs

using Ocean::Tracking::UnidirectionalCorrespondences::CorrespondencePairs = std::vector<CorrespondencePair>

Definition of a vector holding correspondence pairs.

Constructor & Destructor Documentation

◆ UnidirectionalCorrespondences()

Ocean::Tracking::UnidirectionalCorrespondences::UnidirectionalCorrespondences	(	const size_t	numberForward,
		const size_t	numberBackward
	)

Creates a new unidirectional correspondences object.

Parameters

numberForward	The number of forward features, with range [1, infinity)
numberBackward	The number of backward features, with range [1, infinity)

Member Function Documentation

◆ addCandidate()

template<bool tThreadSafe>

void Ocean::Tracking::UnidirectionalCorrespondences::addCandidate	(	const unsigned int	forwardIndex,
		const unsigned int	backwardIndex
	)

Adds a new feature correspondence candidate.

Parameters

forwardIndex	Index of the forward feature or descriptor, with range [0, sizeForward-1]
backwardIndex	Index of the corresponding backward feature or descriptor, with range [0, sizeBackward-1]

Template Parameters

tThreadSafe True, in case the call needs to be thread-safe; False, if no other thread is currently using this correspondence object

◆ correspondences()

CorrespondencePairs Ocean::Tracking::UnidirectionalCorrespondences::correspondences ( ) const

Returns all unidirectional feature correspondences.

Returns: The resulting unique feature correspondences

◆ countBijectiveCorrespondences()

static size_t Ocean::Tracking::UnidirectionalCorrespondences::countBijectiveCorrespondences	(	const Index32 *	usedPointIndices,
		const size_t	size
	)

static

Counts the number of bijective correspondences based on provided indices of used points (either image points or object points).

In case a point index shows up more than once, the point is not part of a bijective correspondence.

Provide the indices of used image points in case the correspondence were determine by iterating over all object points and finding the best matching image point, in such a case an image point could be used more than once:

objectPoint0 -> imagePoint0

objectPoint2 -> imagePoint1        the imagePoint1 is not part of a bijective correspondence
objectPoint4 -> imagePoint1

objectPoint7 -> imagePoint5

objectPoint8 -> imagePoint3

Provide the indices of used object points in case the correspondence were determine by iterating over all image points and finding the best matching object point, in such a case an object point could be used more than once:

imagePoint0 -> objectPoint0

imagePoint1 -> objectPoint2        the objectPoint2 is not part of a bijective correspondence
imagePoint2 -> objectPoint2

imagePoint4 -> objectPoint3

Parameters

usedPointIndices	The indices of the points to be checked, must be valid
size	The number of indices, with range [1, infinity)

Returns: The number of bijective correspondences, with range [0, size]

◆ countNonBijectiveCorrespondences()

static size_t Ocean::Tracking::UnidirectionalCorrespondences::countNonBijectiveCorrespondences	(	const Index32 *	usedPointIndices,
		const size_t	size
	)

static

Counts the number of non-bijective correspondences based on provided indices of used points (either image points or object points).

The function determines how many points have more than one correspondence, while each non-bijective correspondence is only counted once.

Parameters

usedPointIndices	The indices of the points to be checked, must be valid
size	The number of indices, with range [1, infinity)

Returns: The number of non-bijective correspondences, with range [0, size/2]

◆ determineCorrespondingDescriptors()

template<typename TDescriptor , typename TDistance , TDistance(*)(const TDescriptor &, const TDescriptor &) tDistanceFunction>

UnidirectionalCorrespondences::CorrespondencePairs Ocean::Tracking::UnidirectionalCorrespondences::determineCorrespondingDescriptors	(	const TDescriptor *	forwardDescriptors,
		const size_t	numberForwardDescriptors,
		const TDescriptor *	backwardDescriptors,
		const size_t	numberBackwardDescriptors,
		const TDistance	maximalDistance,
		Worker *	worker
	)

static

Determines unidirectional correspondences pairs between two sets of descriptors.

Parameters

forwardDescriptors	The first (forward) set of descriptors, can be invalid if 'numberForwardDescriptors == 0'
numberForwardDescriptors	The number of descriptors in the first set, with range [0, infinity)
backwardDescriptors	The second (backward) set of descriptors, can be invalid if 'numberBackwardDescriptors == 0'
numberBackwardDescriptors	The number of descriptors in the second set, with range [0, infinity)
maximalDistance	The maximal distance between two descriptors to count as match, with range [0, infinity) @parma worker Optional worker to distribute the computation

Returns: The resulting pairs with unidirectional correspondences

Template Parameters

TDescriptor	The data type of the descriptors
TDistance	The data type of the distance between two descriptors
tDistanceFunction	The function returning the distance between two descriptors

◆ determineCorrespondingDescriptorsSubset()

template<typename TDescriptor , typename TDistance , TDistance(*)(const TDescriptor &, const TDescriptor &) tDistanceFunction, unsigned int tLocks>

void Ocean::Tracking::UnidirectionalCorrespondences::determineCorrespondingDescriptorsSubset	(	const TDescriptor *	forwardDescriptors,
		const size_t	numberForwardDescriptors,
		const TDescriptor *	backwardDescriptors,
		const size_t	numberBackwardDescriptors,
		const TDistance	maximalDistance,
		Index32 *	forwardIndicesForBackwardDescriptors,
		Lock *	locks,
		const unsigned int	subsetFirstForwardDescriptor,
		const unsigned int	subsetNumberForwardDescriptors
	)

staticprotected

Determines a subset of all unidirectional correspondences pairs between two sets of descriptors.

Parameters

forwardDescriptors	The first (forward) set of descriptors, must be valid
numberForwardDescriptors	The number of descriptors in the first set, with range [1, infinity)
backwardDescriptors	The second (backward) set of descriptors, must be valid
numberBackwardDescriptors	The number of descriptors in the second set, with range [1, infinity)
maximalDistance	The maximal distance between two descriptors to count as match, with range [0, infinity)
forwardIndicesForBackwardDescriptors	The individual indices of matching forward descriptors, one for each backward descriptor
locks	The 'tLocks' locks elements, must be valid if 'tLocks >= 1'
subsetFirstForwardDescriptor	The first forward descriptor to be handled, with range [0, numberForwardDescriptors-1]
subsetNumberForwardDescriptors	The number of forward descriptors to be handled, with range [1, numberForwardDescriptors-subsetFirstForwardDescriptor]

Returns: The resulting pairs with unidirectional correspondences

Template Parameters

TDescriptor	The data type of the descriptors
TDistance	The data type of the distance between two descriptors
tDistanceFunction	The function returning the distance between two descriptors
tLocks	The number of provided lock objects, with range [0, infinity)

◆ determineCorrespondingFeatures()

template<typename TDescriptor , typename TDistance , TDistance(*)(const TDescriptor &, const TDescriptor &) tDistanceFunction>

UnidirectionalCorrespondences::CorrespondencePairs Ocean::Tracking::UnidirectionalCorrespondences::determineCorrespondingFeatures	(	const AnyCamera &	camera,
		const HomogenousMatrix4 &	world_T_camera,
		const Vector3 *	objectPoints,
		const TDescriptor *	objectPointDescriptors,
		const size_t	numberObjectFeatures,
		const Vector2 *	imagePoints,
		const TDescriptor *	imagePointDescriptors,
		const size_t	numberImageFeatures,
		const TDistance	maximalDistance,
		const Scalar	maximalProjectionError
	)

static

Determines guided unidirectional correspondence pairs between image features and object features.

The resulting matches are guided based on a given rough 6-DOF camera pose.

Parameters

camera	The camera profile defining the projection, must be valid
world_T_camera	The rough 6-DOF pose of the camera, with default camera pointing towards the negative z-space with y-axis upwards
objectPoints	The 3D locations of the 3D object features, one for each object feature, must be valid
objectPointDescriptors	The descriptors of the 3D object features, one for each object feature, must be valid
numberObjectFeatures	The number of 3D object features, with range [1, infinity)
imagePoints	The 2D location of the 2D image features, one for each image feature, must be valid
imagePointDescriptors	The descriptors of the 2D image features, one for each image feature, must be valid
numberImageFeatures	The number of 2D image features, with range [1, infinity)
maximalDistance	The maximal distance between two descriptors (an object descriptor and an image descriptor) to count as match, with range [0, infinity)
maximalProjectionError	The maximal projection error between image features and projected object features to count as candidate (allows to balance the number of candidates based on the precision of the given camera pose), in pixels, with range [0, infinity)

Template Parameters

TDescriptor	The data type of the descriptors
TDistance	The data type of the distance between two descriptors
tDistanceFunction	The function returning the distance between two descriptors

◆ extractCorrespondenceElements()

template<typename TFirst , typename TSecond >

void Ocean::Tracking::UnidirectionalCorrespondences::extractCorrespondenceElements	(	const CorrespondencePairs &	correspondencePairs,
		const TFirst *	firstElements,
		const size_t	sizeFirstElements,
		const TSecond *	secondElements,
		const size_t	sizeSecondElements,
		std::vector< TFirst > &	correspondenceFirstElements,
		std::vector< TSecond > &	correspondenceSecondElements
	)

static

Extracts corresponding elements based on correspondence pairs.

Parameters

correspondencePairs	The correspondence pairs providing the individual indices of the elements to be extracted
firstElements	The entire set of first elements, the first index of each correspondence pair belongs to these elements, must be valid
sizeFirstElements	The size of the entire set of first elements, with range [1, infinity)
secondElements	The entire set of second elements, the second index of each correspondence pair belongs to these elements, must be valid
sizeSecondElements	The size of the entire set of second elements, with range [1, infinity)
correspondenceFirstElements	The resulting elements from the first set which were defined in the provided correspondence pairs
correspondenceSecondElements	The resulting elements from the second set which were define i the provided correspondence pairs, one for each elements in correspondenceFirstElements

Template Parameters

TFirst	The data type of the first elements
TSecond	The data type of the second elements

◆ removeNonBijectiveCorrespondences()

static void Ocean::Tracking::UnidirectionalCorrespondences::removeNonBijectiveCorrespondences	(	const AnyCamera &	camera,
		const HomogenousMatrix4 &	world_T_camera,
		const Vector3 *	objectPoints,
		const Vector2 *	imagePoints,
		Indices32 &	objectPointIndices,
		Indices32 &	imagePointIndices,
		const bool	checkImagePoints
	)

static

Removes non-bijective correspondences from 2D/3D correspondences.

The function will remove all non-bijective correspondences from the provided point indices.

Parameters

camera	The camera profile defining the projection, must be valid
world_T_camera	The camera pose transforming camera to world, with default camera pointing towards the negative z-space with y-axis upwards, must be valid
objectPoints	All 3D object points in which the correspondences are defined, must be valid
imagePoints	All 2D image points in which the correspondences are defined, must be valid
objectPointIndices	The indices of the 3D object points which which correspond to 2D image points, at least one
imagePointIndices	The indices of the 2D image points which which correspond to 3D object points, one for each 3D object point, at least one
checkImagePoints	True, to check the provided image point indices for bijective correspondences; False, to check the provided object point indices for bijective correspondences

Field Documentation

◆ backwardCounters_

Indices32 Ocean::Tracking::UnidirectionalCorrespondences::backwardCounters_

protected

Correspondence counter for backward features (or for the second features).

◆ candidates_

CorrespondencePairs Ocean::Tracking::UnidirectionalCorrespondences::candidates_

protected

Correspondence candidates.

◆ forwardCounters_

Indices32 Ocean::Tracking::UnidirectionalCorrespondences::forwardCounters_

protected

Correspondence counter for forward features (or for the first features).

◆ lock_

Lock Ocean::Tracking::UnidirectionalCorrespondences::lock_

mutableprotected

The object's lock.

◆ matchCounterTwo_

constexpr Index32 Ocean::Tracking::UnidirectionalCorrespondences::matchCounterTwo_ = Index32(-2)

staticconstexprprotected

Definition of a match count value for two+ matches.

◆ matchCountZero_

constexpr Index32 Ocean::Tracking::UnidirectionalCorrespondences::matchCountZero_ = Index32(-1)

staticconstexprprotected

Definition of a match count value for zero matches.

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

UnidirectionalCorrespondences.h

Public Types

Public Member Functions

Static Public Member Functions

Static Protected Member Functions

Protected Attributes

Static Protected Attributes

Detailed Description

Member Typedef Documentation

◆ CorrespondencePair

◆ CorrespondencePairs

Constructor & Destructor Documentation

◆ UnidirectionalCorrespondences()

Member Function Documentation

◆ addCandidate()

◆ correspondences()

◆ countBijectiveCorrespondences()

◆ countNonBijectiveCorrespondences()

◆ determineCorrespondingDescriptors()

◆ determineCorrespondingDescriptorsSubset()

◆ determineCorrespondingFeatures()

◆ extractCorrespondenceElements()

◆ removeNonBijectiveCorrespondences()

Field Documentation

◆ backwardCounters_

◆ candidates_

◆ forwardCounters_

◆ lock_

◆ matchCounterTwo_

◆ matchCountZero_