template<class _ccImT>
class mx::improc::imageXCorrDiscrete< _ccImT >

Find the optimum shift to align two images using the discrete cross correlation.

The reference image must be smaller than the target image. Both the reference image and the section of target image being analyzed are mean subtracted and variance normalized. An optional mask can be supplied, which limits the pixels used for the mean and variance calculation.

Typical usage will be to set the mask, then the reference, then repeatedly call operator() to determine the shifts for a sequence of imaages. No new heap allocations take place on these calls to operator(), and the reference image is not re-normalized on each call.

The shift is reported in pixels such that if the mxlib imageShift function is used to shift the input image by the negative of the shifts, it will align with the reference at the center of the array.

Three peak finding methods are provided. xcorrPeakMethod::centroid uses center of light, xcorrPeakMethod::gaussfit uses Gaussian centroiding, and xcorrPeakMethod::interp uses interpolation to find the peak to a given tolerance.

Template Parameters

_ccImT is the Eigen-like array type used for image processing. See typedefs.

Definition at line 72 of file imageXCorrDiscrete.hpp.

#include <improc/imageXCorrDiscrete.hpp>

Public Types
typedef _ccImT	ccImT
	the Eigen-like array type used for image processing
typedef _ccImT::Scalar	Scalar
	the scalar type of the image type

Public Member Functions
	imageXCorrDiscrete ()
	Default c'tor.
	imageXCorrDiscrete (int maxLag)
	Construct seeting maxLag.
int	maxLag ()
	Get the current maximum lag.
void	maxLag (int ml)
	Set the maximum lag.
Scalar	tol ()
	Get the tolerance of the interpolated-magnified image, in pixels.
void	tol (Scalar nt)
	Set the tolerance of the interpolated-magnified image, in pixels.
int	resize (int nrows, int ncols)
	Set the size of the cross-correlation images.
int	maskIm (const ccImT &mask)
	Set the mask image.
const ccImT &	maskIm ()
	Get a reference to the mask image.
int	refIm (const ccImT &im0)
	Set the reference image.
const ccImT &	refIm ()
	Get a reference to the reference image.
const ccImT &	normIm ()
	Get a reference to the normalized image.
const ccImT &	ccIm ()
	Get a reference to the cross correlation image.
const ccImT &	magIm ()
	Get a reference to the magnified image.
template<class imT>
int	operator() (Scalar &xShift, Scalar &yShift, const imT &im)
	Conduct the cross correlation to a specified tolerance.

Public Attributes
int	m_maxLag { 0 }
	The maximum lag to consider in the initial cross-correlation.
Scalar	m_tol { 0.1 }
	The tolerance of the interpolated-magnified image, in pixels.
Scalar	m_magSize { 0 }
	Magnified size of the ccIm when using interp. Set as function of m_tol and m_maxLag.
Working Memory
ccImT	m_refIm
	The normalized reference image.
ccImT	m_maskIm
	Mask image to use, may be needed for proper normalization even if refIm has 0 mask applied.
ccImT	m_normIm
	The normalized image.
ccImT	m_ccIm
	The cross-correlation image.
ccImT	m_magIm
	The magnified image, or empty when interpolation falls back to the discrete peak.

Member Typedef Documentation

◆ ccImT

template<class _ccImT>

typedef _ccImT mx::improc::imageXCorrDiscrete< _ccImT >::ccImT

the Eigen-like array type used for image processing

Definition at line 75 of file imageXCorrDiscrete.hpp.

◆ Scalar

template<class _ccImT>

typedef _ccImT::Scalar mx::improc::imageXCorrDiscrete< _ccImT >::Scalar

the scalar type of the image type

Definition at line 76 of file imageXCorrDiscrete.hpp.

Constructor & Destructor Documentation

◆ imageXCorrDiscrete() [1/2]

template<class ccImT>

mx::improc::imageXCorrDiscrete< ccImT >::imageXCorrDiscrete ( )

Default c'tor.

Definition at line 208 of file imageXCorrDiscrete.hpp.

◆ imageXCorrDiscrete() [2/2]

template<class ccImT>

mx::improc::imageXCorrDiscrete< ccImT >::imageXCorrDiscrete ( int maxLag )

explicit

Construct seeting maxLag.

Definition at line 213 of file imageXCorrDiscrete.hpp.

References maxLag().

Member Function Documentation

◆ ccIm()

template<class ccImT>

const ccImT & mx::improc::imageXCorrDiscrete< ccImT >::ccIm ( )

Get a reference to the cross correlation image.

Returns: a const referent to m_ccIm.

Definition at line 309 of file imageXCorrDiscrete.hpp.

References m_ccIm.

Referenced by TEST_CASE().

◆ magIm()

template<class ccImT>

const ccImT & mx::improc::imageXCorrDiscrete< ccImT >::magIm ( )

Get a reference to the magnified image.

Returns: a const referent to m_magIm.

Definition at line 315 of file imageXCorrDiscrete.hpp.

References m_magIm.

Referenced by TEST_CASE().

◆ maskIm() [1/2]

template<class ccImT>

const ccImT & mx::improc::imageXCorrDiscrete< ccImT >::maskIm ( )

Get a reference to the mask image.

Returns: a const referance to the mask image.

Definition at line 265 of file imageXCorrDiscrete.hpp.

References m_maskIm.

◆ maskIm() [2/2]

template<class ccImT>

int mx::improc::imageXCorrDiscrete< ccImT >::maskIm ( const ccImT & mask )

Set the mask image.

Returns: 0 on success; -1 on error

Parameters

[in] mask the new mask image

Definition at line 256 of file imageXCorrDiscrete.hpp.

References m_maskIm.

Referenced by TEST_CASE().

◆ maxLag() [1/2]

template<class ccImT>

int mx::improc::imageXCorrDiscrete< ccImT >::maxLag ( )

Get the current maximum lag.

Returns: the current value of m_maxLag

Definition at line 219 of file imageXCorrDiscrete.hpp.

References m_maxLag.

Referenced by imageXCorrDiscrete().

◆ maxLag() [2/2]

template<class ccImT>

void mx::improc::imageXCorrDiscrete< ccImT >::maxLag ( int ml )

Set the maximum lag.

Parameters

[in] ml the new maximum lag

Definition at line 225 of file imageXCorrDiscrete.hpp.

References m_maxLag, m_tol, and tol().

◆ normIm()

template<class ccImT>

const ccImT & mx::improc::imageXCorrDiscrete< ccImT >::normIm ( )

Get a reference to the normalized image.

Returns: a const referent to m_normIm.

Definition at line 303 of file imageXCorrDiscrete.hpp.

References m_normIm.

◆ operator()()

template<class ccImT>

template<class imT>

int mx::improc::imageXCorrDiscrete< ccImT >::operator()	(	Scalar &	xShift,
		Scalar &	yShift,
		const imT &	im )

Conduct the cross correlation to a specified tolerance.

Cubic interpolation requires at least five correlation samples in each dimension and cannot interpolate a maximum on the outer boundary. It also pads unsupported magnified borders with zero, which would dominate a non-positive correlation surface. In these cases, this falls back to the discrete correlation maximum and leaves magIm() empty.

Returns: 0 on success; -1 on error

Parameters

[out]	xShift	the x shift of im w.r.t. im0, in pixels
[out]	yShift	the y shift of im w.r.t. im0, in pixels
[in]	im	the image to cross-correlate with the reference

Definition at line 322 of file imageXCorrDiscrete.hpp.

References mx::improc::imageCenterOfLight(), mx::improc::imageMagnify(), mx::improc::imageMean(), mx::improc::imageVariance(), mx::invalidarg, mx::math::isFinite(), m_ccIm, m_magIm, m_magSize, m_maskIm, m_maxLag, m_normIm, m_refIm, m_tol, mx::internal::mxlib_error_report(), and mx::sizeerr.

◆ refIm() [1/2]

template<class ccImT>

const ccImT & mx::improc::imageXCorrDiscrete< ccImT >::refIm ( )

Get a reference to the reference image.

Returns: a const referent to m_refIm.

Definition at line 297 of file imageXCorrDiscrete.hpp.

References m_refIm.

◆ refIm() [2/2]

template<class ccImT>

int mx::improc::imageXCorrDiscrete< ccImT >::refIm ( const ccImT & im0 )

Set the reference image.

Normalizes the reference image by mean subtraction and variance division. Applies the mask first if supplied.

Returns: 0 on success; -1 on error

Definition at line 271 of file imageXCorrDiscrete.hpp.

References mx::improc::imageMean(), mx::improc::imageVariance(), m_maskIm, m_refIm, mx::internal::mxlib_error_report(), and mx::sizeerr.

Referenced by TEST_CASE().

◆ resize()

template<class _ccImT>

int mx::improc::imageXCorrDiscrete< _ccImT >::resize	(	int	nrows,
		int	ncols )

Set the size of the cross-correlation images.

This resizes all working memory.

Returns: 0 on success; -1 on error

Parameters

[in]	nrows	the number of rows in the images to register
[in]	ncols	the number of columns in the images to register

◆ tol() [1/2]

template<class ccImT>

ccImT::Scalar mx::improc::imageXCorrDiscrete< ccImT >::tol ( )

Get the tolerance of the interpolated-magnified image, in pixels.

Returns: the current value of m_tol.

Definition at line 232 of file imageXCorrDiscrete.hpp.

References m_tol.

Referenced by maxLag().

◆ tol() [2/2]

template<class ccImT>

void mx::improc::imageXCorrDiscrete< ccImT >::tol ( Scalar nt )

Set the tolerance of the interpolated-magnified image, in pixels.

Parameters

[in] nt The new value of the interpolation tolerance.

Definition at line 238 of file imageXCorrDiscrete.hpp.

References mx::math::isFinite(), m_magSize, m_maxLag, and m_tol.

Member Data Documentation

◆ m_ccIm

template<class _ccImT>

ccImT mx::improc::imageXCorrDiscrete< _ccImT >::m_ccIm

The cross-correlation image.

Definition at line 92 of file imageXCorrDiscrete.hpp.

Referenced by ccIm(), and operator()().

◆ m_magIm

template<class _ccImT>

ccImT mx::improc::imageXCorrDiscrete< _ccImT >::m_magIm

The magnified image, or empty when interpolation falls back to the discrete peak.

Definition at line 94 of file imageXCorrDiscrete.hpp.

Referenced by magIm(), and operator()().

◆ m_magSize

template<class _ccImT>

Scalar mx::improc::imageXCorrDiscrete< _ccImT >::m_magSize { 0 }

Magnified size of the ccIm when using interp. Set as function of m_tol and m_maxLag.

Definition at line 104 of file imageXCorrDiscrete.hpp.

Referenced by operator()(), and tol().

◆ m_maskIm

template<class _ccImT>

ccImT mx::improc::imageXCorrDiscrete< _ccImT >::m_maskIm

Mask image to use, may be needed for proper normalization even if refIm has 0 mask applied.

Definition at line 86 of file imageXCorrDiscrete.hpp.

Referenced by maskIm(), maskIm(), operator()(), and refIm().

◆ m_maxLag

template<class _ccImT>

int mx::improc::imageXCorrDiscrete< _ccImT >::m_maxLag { 0 }

The maximum lag to consider in the initial cross-correlation.

Definition at line 100 of file imageXCorrDiscrete.hpp.

Referenced by maxLag(), maxLag(), operator()(), and tol().

◆ m_normIm

template<class _ccImT>

ccImT mx::improc::imageXCorrDiscrete< _ccImT >::m_normIm

The normalized image.

Definition at line 90 of file imageXCorrDiscrete.hpp.

Referenced by normIm(), and operator()().

◆ m_refIm

template<class _ccImT>

ccImT mx::improc::imageXCorrDiscrete< _ccImT >::m_refIm

The normalized reference image.

Definition at line 84 of file imageXCorrDiscrete.hpp.

Referenced by operator()(), refIm(), and refIm().

◆ m_tol

template<class _ccImT>

Scalar mx::improc::imageXCorrDiscrete< _ccImT >::m_tol { 0.1 }

The tolerance of the interpolated-magnified image, in pixels.

Definition at line 102 of file imageXCorrDiscrete.hpp.

Referenced by maxLag(), operator()(), tol(), and tol().

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

improc/imageXCorrDiscrete.hpp

Public Types

Public Member Functions

Public Attributes

Member Typedef Documentation

◆ ccImT

◆ Scalar

Constructor & Destructor Documentation

◆ imageXCorrDiscrete() [1/2]

◆ imageXCorrDiscrete() [2/2]

Member Function Documentation

◆ ccIm()

◆ magIm()

◆ maskIm() [1/2]

◆ maskIm() [2/2]

◆ maxLag() [1/2]

◆ maxLag() [2/2]

◆ normIm()

◆ operator()()

◆ refIm() [1/2]

◆ refIm() [2/2]

◆ resize()

◆ tol() [1/2]

◆ tol() [2/2]

Member Data Documentation

◆ m_ccIm

◆ m_magIm

◆ m_magSize

◆ m_maskIm

◆ m_maxLag

◆ m_normIm

◆ m_refIm

◆ m_tol