This class implements the possibility to find local maximum in a 2D array by applying a non-maximum-suppression search. More...

#include <NonMaximumSuppression.h>

Data Structures
class	StrengthCandidate
	This class holds the horizontal position and strength parameter of an interest pixel. More...

class	StrengthPosition
	This class extends a 2D position by a third parameter storing a strength value. More...

Public Types
template<typename TCoordinate , typename TStrength >
using	StrengthPositions = std::vector< StrengthPosition< TCoordinate, TStrength > >
	Definition of a vector holding strength pixel positions.

template<typename TCoordinate , typename TStrength >
using	PositionCallback = Callback< bool, const unsigned int, const unsigned int, const T, TCoordinate &, TCoordinate &, TStrength & >
	Definition of a callback function used to determine the precise sub-pixel position of a specific point.

Public Member Functions
	NonMaximumSuppression (NonMaximumSuppression< T > &&nonMaximumSuppression) noexcept
	Move constructor.

	NonMaximumSuppression (const NonMaximumSuppression< T > &nonMaximumSuppression) noexcept
	Copy constructor.

	NonMaximumSuppression (const unsigned int width, const unsigned int height, const unsigned int yOffset=0u) noexcept
	Creates a new maximum suppression object with a predefined size.

unsigned int	width () const
	Returns the width of this object.

unsigned int	height () const
	Returns the height of this object.

unsigned int	yOffset () const
	Returns the optional offset in the vertical direction.

void	addCandidate (const unsigned int x, const unsigned int y, const T &strength)
	Adds a new candidate to this object.

void	addCandidates (const T values, const unsigned int valuesPaddingElements, const unsigned int firstColumn, const unsigned int numberColumns, const unsigned int firstRow, const unsigned int numberRows, const T &minimalThreshold, Worker worker)
	Adds new candidates to this object from a given buffer providing one value for each bin/pixel of this object.

void	removeCandidatesRightFrom (const unsigned int x, const unsigned int y)
	Removes all candidates from a specified row having a horizontal location equal or larger than a specified coordinate.

template<typename TCoordinate , typename TStrength , bool tStrictMaximum = true>
StrengthPositions< TCoordinate, TStrength >	suppressNonMaximum (const unsigned int firstColumn, const unsigned int numberColumns, const unsigned int firstRow, const unsigned int numberRows, Worker worker=nullptr, const PositionCallback< TCoordinate, TStrength > positionCallback=nullptr) const
	Applies a non-maximum-suppression search on a given 2D frame in a 3x3 neighborhood (eight neighbors).

void	reset ()
	Removes the gathered non-maximum suppression information so that this object can be reused again (for the same task with same resolution etc.).

NonMaximumSuppression< T > &	operator= (NonMaximumSuppression< T > &&nonMaximumSuppression)
	Move operator.

NonMaximumSuppression< T > &	operator= (const NonMaximumSuppression< T > &nonMaximumSuppression)
	Copy operator.

template<typename TCoordinate , typename TStrength , bool tStrictMaximum>
NonMaximumSuppression< T >::template StrengthPositions< TCoordinate, TStrength >	suppressNonMaximum (const unsigned int firstColumn, const unsigned int numberColumns, const unsigned int firstRow, const unsigned int numberRows, Worker worker, const PositionCallback< TCoordinate, TStrength > positionCallback) const

template<typename TCoordinate , typename TStrength , bool tStrictMaximum>
NonMaximumSuppression< T >::template StrengthPositions< TCoordinate, TStrength >	suppressNonMaximum (const unsigned int width, const unsigned int height, const StrengthPositions< TCoordinate, TStrength > &strengthPositions, const TCoordinate radius, Indices32 *validIndices)

Static Public Member Functions
template<typename TCoordinate , typename TStrength , bool tStrictMaximum>
static StrengthPositions< TCoordinate, TStrength >	suppressNonMaximum (const unsigned int width, const unsigned int height, const StrengthPositions< TCoordinate, TStrength > &strengthPositions, const TCoordinate radius, Indices32 *validIndices=nullptr)
	Applies a non-maximum-suppression based on already existing strength positions (just with a custom suppression radius) e.g., as a post-processing step.

template<typename TFloat >
static bool	determinePrecisePeakLocation1 (const T &leftValue, const T &middleValue, const T &rightValue, TFloat &location)
	Determines the precise peak location in 1D space for three discrete neighboring measurements at location x == 0.

template<typename TFloat >
static bool	determinePrecisePeakLocation2 (const T const topValues, const T const centerValues, const T *const bottomValues, VectorT2< TFloat > &location)
	Determines the precise peak location in 2D space for nine discrete neighboring measurements at location x == 0, y == 0.

Private Types
typedef std::vector< StrengthCandidate >	StrengthCandidateRow
	Definition of a vector holding strength candidate objects.

typedef ShiftVector< StrengthCandidateRow >	StrengthCandidateRows
	Definition of a vector holding a vector of strength candidates.

Private Member Functions
void	addCandidatesSubset (const T values, const unsigned int valuesStrideElements, const unsigned int firstColumn, const unsigned int numberColumns, const T minimalThreshold, const unsigned int firstRow, const unsigned int numberRows)
	Adds new candidates to this object from a subset of a given buffer providing one value for each bin/pixel of this object.

template<typename TCoordinate , typename TStrength , bool tStrictMaximum>
void	suppressNonMaximumSubset (StrengthPositions< TCoordinate, TStrength > strengthPositions, const unsigned int firstColumn, const unsigned int firstRow, Lock lock, const PositionCallback< TCoordinate, TStrength > *positionCallback, const unsigned int numberColumns, const unsigned int numberRows) const
	Applies a non-maximum-suppression search on a subset of a given 2D frame in a 3x3 neighborhood (eight neighbors).

Private Attributes
unsigned int	width_ = 0u
	Width of this object.

StrengthCandidateRows	rows_
	All candidate rows.

Detailed Description

template<typename T>
class Ocean::CV::NonMaximumSuppression< T >

This class implements the possibility to find local maximum in a 2D array by applying a non-maximum-suppression search.

The search is done within a 3x3 neighborhood (centered around the point of interest).
Use this class to determine e.g. reliable feature points.
The class supports bin accuracy (pixel accuracy) and sub-bin accuracy (sub-pixel accuracy).

The non-maximum-suppression search is implemented by a vertical list holding maps of horizontal array elements.
The performance depends on the number of elements inserted into the individual maps.
Thus, do not add data elements with negligible value.

It should be mentioned that the application of this class should be restricted to situations in which the entire filter response values do not exist already.
The performance boost comes with a simultaneous determination of filter responses and the insertion of possible candidates for maximum locations.

Template Parameters

T	The data type of the individual elements that are applied for the non-maximum-suppression search.

Member Typedef Documentation

◆ PositionCallback

template<typename T >

template<typename TCoordinate , typename TStrength >

using Ocean::CV::NonMaximumSuppression< T >::PositionCallback = Callback<bool, const unsigned int, const unsigned int, const T, TCoordinate&, TCoordinate&, TStrength&>

Definition of a callback function used to determine the precise sub-pixel position of a specific point.

The first parameter provides the horizontal position.
The second parameter provides the vertical position.
The third parameter provides the strength value.
The fourth parameter receives the precise horizontal position.
The fifth parameter receives the precise vertical position.
The sixth parameter receives the precise strength value.
The return parameter should be True if the precise position could be determined

◆ StrengthCandidateRow

template<typename T >

typedef std::vector<StrengthCandidate> Ocean::CV::NonMaximumSuppression< T >::StrengthCandidateRow

private

Definition of a vector holding strength candidate objects.

◆ StrengthCandidateRows

template<typename T >

typedef ShiftVector<StrengthCandidateRow> Ocean::CV::NonMaximumSuppression< T >::StrengthCandidateRows

private

Definition of a vector holding a vector of strength candidates.

◆ StrengthPositions

template<typename T >

template<typename TCoordinate , typename TStrength >

using Ocean::CV::NonMaximumSuppression< T >::StrengthPositions = std::vector<StrengthPosition<TCoordinate, TStrength> >

Definition of a vector holding strength pixel positions.

Constructor & Destructor Documentation

◆ NonMaximumSuppression() [1/3]

template<typename T >

Ocean::CV::NonMaximumSuppression< T >::NonMaximumSuppression ( NonMaximumSuppression< T > && nonMaximumSuppression )

noexcept

Move constructor.

Parameters

nonMaximumSuppression The object to be moved

◆ NonMaximumSuppression() [2/3]

template<typename T >

Ocean::CV::NonMaximumSuppression< T >::NonMaximumSuppression ( const NonMaximumSuppression< T > & nonMaximumSuppression )

noexcept

Copy constructor.

Parameters

nonMaximumSuppression The object to be moved

◆ NonMaximumSuppression() [3/3]

template<typename T >

Ocean::CV::NonMaximumSuppression< T >::NonMaximumSuppression	(	const unsigned int	width,
		const unsigned int	height,
		const unsigned int	yOffset = `0u`
	)

noexcept

Creates a new maximum suppression object with a predefined size.

Parameters

width	The width of this object in pixel, with range [3, infinity)
height	The height of this object in pixel, with range [3, infinity)
yOffset	Optional offset in the vertical direction moving the suppression region by the specified number of rows, with range [0, infinity)

Member Function Documentation

◆ addCandidate()

template<typename T >

void Ocean::CV::NonMaximumSuppression< T >::addCandidate	(	const unsigned int	x,
		const unsigned int	y,
		const T &	strength
	)

inline

Adds a new candidate to this object.

Beware: Due to performance issues do no add candidates with negligible strength parameter.

Parameters

x	Horizontal position in pixel, with range [0, width() - 1]
y	Vertical position in pixel, with range [yOffset(), yOffset() + height() - 1]
strength	The strength parameter

See also: addCandidates(), removeCandidatesFromRight().

◆ addCandidates()

template<typename T >

void Ocean::CV::NonMaximumSuppression< T >::addCandidates	(	const T *	values,
		const unsigned int	valuesPaddingElements,
		const unsigned int	firstColumn,
		const unsigned int	numberColumns,
		const unsigned int	firstRow,
		const unsigned int	numberRows,
		const T &	minimalThreshold,
		Worker *	worker
	)

Adds new candidates to this object from a given buffer providing one value for each bin/pixel of this object.

Beware: Due to performance reasons, you should use the addCandidate() function to add one single new candidate in the moment the filter response is larger than a specific threshold.

Parameters

values	The from which candidates will be added, must be width() * height() elements
valuesPaddingElements	The number of padding elements at the end of each values row, in elements, with range [0, infinity)
firstColumn	First column to be handled, with range [0, width() - 1]
numberColumns	Number of columns to be handled, with range [1, width() - firstColumn]
firstRow	First row to be handled, with range [yOffset(), height() - 1]
numberRows	Number of rows to be handled, with range [1, height() - firstRow]
minimalThreshold	The minimal threshold so that a value counts as candidate
worker	Optional worker object to distribute the computation

See also: addCandidate(), removeCandidatesFromRight().

◆ addCandidatesSubset()

template<typename T >

void Ocean::CV::NonMaximumSuppression< T >::addCandidatesSubset	(	const T *	values,
		const unsigned int	valuesStrideElements,
		const unsigned int	firstColumn,
		const unsigned int	numberColumns,
		const T *	minimalThreshold,
		const unsigned int	firstRow,
		const unsigned int	numberRows
	)

private

Adds new candidates to this object from a subset of a given buffer providing one value for each bin/pixel of this object.

Parameters

values	The from which candidates will be added, must be width() * height() elements
valuesStrideElements	The number of elements between two values rows, in elements, with range [0, infinity)
minimalThreshold	The minimal threshold so that a value counts as candidate
firstColumn	First column to be handled, with range [0, width() - 1]
numberColumns	Number of columns to be handled, with range [1, width() - firstColumn]
firstRow	The first row in the buffer from which the candidates will be added, with range [yOffset(), height())
numberRows	The number of rows to be handled, with range [1, height() - firstRow]

See also: addCandidates().

◆ determinePrecisePeakLocation1()

template<typename T >

template<typename TFloat >

bool Ocean::CV::NonMaximumSuppression< T >::determinePrecisePeakLocation1	(	const T &	leftValue,
		const T &	middleValue,
		const T &	rightValue,
		TFloat &	location
	)

static

Determines the precise peak location in 1D space for three discrete neighboring measurements at location x == 0.

The precise peak is determined based on the first and second derivatives of the measurement values.

Parameters

leftValue	The left discrete value, e.g., at location x - 1, with range (-infinity, middleValue]
middleValue	The middle discrete value, e.g., at location x, with range (-infinity, infinity)
rightValue	The discrete value, e.g., at location x + 1, with range (-infinity, middleValue]
location	The location of the precise peak of all values, with range (-1, 1)

Returns: True, if succeeded

Template Parameters

TFloat The floating point data type to be used for calculation, either 'float' or 'double'

◆ determinePrecisePeakLocation2()

template<typename T >

template<typename TFloat >

bool Ocean::CV::NonMaximumSuppression< T >::determinePrecisePeakLocation2	(	const T *const	topValues,
		const T *const	centerValues,
		const T *const	bottomValues,
		VectorT2< TFloat > &	location
	)

static

Determines the precise peak location in 2D space for nine discrete neighboring measurements at location x == 0, y == 0.

The precise peak is determined based on the first and second derivatives of the measurement values.

Parameters

topValues	The three discrete values in the top row, must be valid
centerValues	The three discrete values in the center row, must be valid
bottomValues	The three discrete values in the bottom row, must be valid
location	The location of the precise peak of all values, with range (-1, 1)

Returns: True, if succeeded

Template Parameters

TFloat The floating point data type to be used for calculation, either 'float' or 'double'

◆ height()

template<typename T >

unsigned int Ocean::CV::NonMaximumSuppression< T >::height ( ) const

inline

Returns the height of this object.

Returns: Height in pixel

◆ operator=() [1/2]

template<typename T >

NonMaximumSuppression< T > & Ocean::CV::NonMaximumSuppression< T >::operator= ( const NonMaximumSuppression< T > & nonMaximumSuppression )

Copy operator.

Parameters

nonMaximumSuppression The object to be copied

Returns: Reference to this object

◆ operator=() [2/2]

template<typename T >

NonMaximumSuppression< T > & Ocean::CV::NonMaximumSuppression< T >::operator= ( NonMaximumSuppression< T > && nonMaximumSuppression )

Move operator.

Parameters

nonMaximumSuppression Object to be moved

Returns: Reference to this object

◆ removeCandidatesRightFrom()

template<typename T >

void Ocean::CV::NonMaximumSuppression< T >::removeCandidatesRightFrom	(	const unsigned int	x,
		const unsigned int	y
	)

inline

Removes all candidates from a specified row having a horizontal location equal or larger than a specified coordinate.

Parameters

x	The horizontal coordinate specifying which candidates will be removed, all candidates with horizontal location >= x will be removed, with range [0, infinity)
y	The index of the row in which the candidates will be removed, with range [yOffset(), yOffset() + height() - 1]

◆ reset()

template<typename T >

void Ocean::CV::NonMaximumSuppression< T >::reset ( )

Removes the gathered non-maximum suppression information so that this object can be reused again (for the same task with same resolution etc.).

The allocated memory will remain so that reusing this object may improve performance.

◆ suppressNonMaximum() [1/4]

template<typename T >

template<typename TCoordinate , typename TStrength , bool tStrictMaximum>

NonMaximumSuppression< T >::template StrengthPositions< TCoordinate, TStrength > Ocean::CV::NonMaximumSuppression< T >::suppressNonMaximum	(	const unsigned int	firstColumn,
		const unsigned int	numberColumns,
		const unsigned int	firstRow,
		const unsigned int	numberRows,
		Worker *	worker,
		const PositionCallback< TCoordinate, TStrength > *	positionCallback
	)		const

◆ suppressNonMaximum() [2/4]

template<typename T >

template<typename TCoordinate , typename TStrength , bool tStrictMaximum = true>

StrengthPositions< TCoordinate, TStrength > Ocean::CV::NonMaximumSuppression< T >::suppressNonMaximum	(	const unsigned int	firstColumn,
		const unsigned int	numberColumns,
		const unsigned int	firstRow,
		const unsigned int	numberRows,
		Worker *	worker = `nullptr`,
		const PositionCallback< TCoordinate, TStrength > *	positionCallback = `nullptr`
	)		const

Applies a non-maximum-suppression search on a given 2D frame in a 3x3 neighborhood (eight neighbors).

This function allows to determine the precise position of the individual maximum value positions by application of a callback function determining the individual positions.

Parameters

firstColumn	First column to be handled, with range [1, width() - 1)
numberColumns	Number of columns to be handled
firstRow	First row to be handled, with range [yOffset() + 1, height() - 1)
numberRows	Number of rows to be handled
worker	Optional worker object to distribute the computation
positionCallback	Optional callback function allowing to determine the precise position of the individual maximum value positions

Returns: Resulting non maximum suppressed positions including the strength parameters

Template Parameters

TCoordinate	The data type of a scalar coordinate
TStrength	The data type of the strength parameter
tStrictMaximum	True, to search for a strict maximum (larger than all eight neighbors); False, to allow equal values in the upper left neighborhood

◆ suppressNonMaximum() [3/4]

template<typename T >

template<typename TCoordinate , typename TStrength , bool tStrictMaximum>

NonMaximumSuppression< T >::template StrengthPositions< TCoordinate, TStrength > Ocean::CV::NonMaximumSuppression< T >::suppressNonMaximum	(	const unsigned int	width,
		const unsigned int	height,
		const StrengthPositions< TCoordinate, TStrength > &	strengthPositions,
		const TCoordinate	radius,
		Indices32 *	validIndices
	)

◆ suppressNonMaximum() [4/4]

template<typename T >

template<typename TCoordinate , typename TStrength , bool tStrictMaximum>

static StrengthPositions< TCoordinate, TStrength > Ocean::CV::NonMaximumSuppression< T >::suppressNonMaximum	(	const unsigned int	width,
		const unsigned int	height,
		const StrengthPositions< TCoordinate, TStrength > &	strengthPositions,
		const TCoordinate	radius,
		Indices32 *	validIndices = `nullptr`
	)

static

Applies a non-maximum-suppression based on already existing strength positions (just with a custom suppression radius) e.g., as a post-processing step.

Parameters

width	The width of the image/domain in which the strength positions are located, e.g., in pixel, with range [1, infinity)
height	The height of the image/domain in which the strength positions are located, e.g., in pixel, with range [1, infinity)
strengthPositions	The strength positions for which a custom suppression-radius will be applied
radius	The suppression radius to be applied, with range [1, infinity)
validIndices	Optional resulting indices of all strength positions which remain after suppression

Returns: The resulting strength positions

Template Parameters

TCoordinate	The data type of a scalar coordinate
TStrength	The data type of the strength parameter
tStrictMaximum	True, to search for a strict maximum (larger than all eight neighbors); False, to allow equal values in the upper left neighborhood

◆ suppressNonMaximumSubset()

template<typename T >

template<typename TCoordinate , typename TStrength , bool tStrictMaximum>

void Ocean::CV::NonMaximumSuppression< T >::suppressNonMaximumSubset	(	StrengthPositions< TCoordinate, TStrength > *	strengthPositions,
		const unsigned int	firstColumn,
		const unsigned int	firstRow,
		Lock *	lock,
		const PositionCallback< TCoordinate, TStrength > *	positionCallback,
		const unsigned int	numberColumns,
		const unsigned int	numberRows
	)		const

private

Applies a non-maximum-suppression search on a subset of a given 2D frame in a 3x3 neighborhood (eight neighbors).

This function allows to determine the precise position of the individual maximum value positions by application of a callback function determining the individual positions.

Parameters

strengthPositions	Resulting non maximum suppressed positions including the strength parameters
firstColumn	First column to be handled
numberColumns	Number of columns to be handled
lock	The lock object that must be defined if this function is executed in parallel on several threads
positionCallback	Optional callback function allowing to determine the precise position of the individual maximum value positions
firstRow	First row to be handled
numberRows	Number of rows to be handled

Template Parameters

tStrictMaximum True, to search for a strict maximum (larger than all eight neighbors); False, to allow equal values in the upper left neighborhood

◆ width()

template<typename T >

unsigned int Ocean::CV::NonMaximumSuppression< T >::width ( ) const

inline

Returns the width of this object.

Returns: Width in pixel

◆ yOffset()

template<typename T >

unsigned int Ocean::CV::NonMaximumSuppression< T >::yOffset ( ) const

inline

Returns the optional offset in the vertical direction.

Returns: Optional vertical direction offset, 0 by default

Field Documentation

◆ rows_

template<typename T >

StrengthCandidateRows Ocean::CV::NonMaximumSuppression< T >::rows_

private

All candidate rows.

◆ width_

template<typename T >

unsigned int Ocean::CV::NonMaximumSuppression< T >::width_ = 0u

private

Width of this object.

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

NonMaximumSuppression.h

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Private Types

Private Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ PositionCallback

◆ StrengthCandidateRow

◆ StrengthCandidateRows

◆ StrengthPositions

Constructor & Destructor Documentation

◆ NonMaximumSuppression() [1/3]

◆ NonMaximumSuppression() [2/3]

◆ NonMaximumSuppression() [3/3]

Member Function Documentation

◆ addCandidate()

◆ addCandidates()

◆ addCandidatesSubset()

◆ determinePrecisePeakLocation1()

◆ determinePrecisePeakLocation2()

◆ height()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ removeCandidatesRightFrom()

◆ reset()

◆ suppressNonMaximum() [1/4]

◆ suppressNonMaximum() [2/4]

◆ suppressNonMaximum() [3/4]

◆ suppressNonMaximum() [4/4]

◆ suppressNonMaximumSubset()

◆ width()

◆ yOffset()

Field Documentation

◆ rows_

◆ width_