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

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

The reference image must be the same size as 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::centerOfLight uses center of light, xcorrPeakMethod::gaussFit uses Gaussian centroiding, and xcorrPeakMethod::interpPeak uses interpolation to find the peak to a given tolerance. For well behaved images gaussFit is most accurate. interpPeak should be robust against weird shapes and other problems, but accuracy is somewhat worse.

Template Parameters

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

Definition at line 68 of file imageXCorrFFT.hpp.

#include <improc/imageXCorrFFT.hpp>

Public Types
typedef _ccImT	ccImT
	the Eigen-like array type used for image processing More...

typedef _ccImT::Scalar	Scalar
	the scalar type of the image type More...

typedef _ccImT::Scalar	realT
	the scalar type of the image type More...

typedef std::complex< realT >	complexT
	Complex floating point type. More...

typedef Eigen::Array< realT, Eigen::Dynamic, Eigen::Dynamic >	realArrayT
	Real eigen array type. More...

typedef Eigen::Array< complexT, Eigen::Dynamic, Eigen::Dynamic >	complexArrayT
	Complex eigen array type with Scalar==complexT. More...

Public Member Functions
	imageXCorrFFT ()
	Default c'tor. More...

	imageXCorrFFT (int maxLag)
	Constructor setting maxLag. More...

int	resize (int nrows, int ncols)
	Set the size of the cross-correlation images. More...

bool	normalize ()
	Get the current value of the normalize flag. More...

void	normalize (bool no)
	Set the normalize flag. More...

int	maxLag ()
	Get the current maximum lag. More...

void	maxLag (int ml)
	Set the maximum lag. More...

Scalar	tol ()
	Get the tolerance of the interpolated-magnified image, in pixels. More...

void	tol (Scalar nt)
	Set the tolerance of the interpolated-magnified image, in pixels. More...

int	maskIm (const ccImT &mask)
	Set the mask image. More...

const ccImT &	maskIm ()
	Get a reference to the mask image. More...

int	refIm (const ccImT &im0)
	Set the reference image. More...

const ccImT &	refIm ()
	Get a reference to the reference image. More...

const ccImT &	normIm ()
	Get a reference to the normalized image. More...

const ccImT &	ccIm ()
	Get a reference to the cross correlation image. More...

const ccImT &	magIm ()
	Get a reference to the magnified image. More...

template<class imT >
int	operator() (Scalar &xShift, Scalar &yShift, const imT &im)
	Conduct the cross correlation to a specified tolerance. More...

template<class im0T , class imT >
int	operator() (Scalar &xShift, Scalar &yShift, im0T &im0, imT &im)
	Conduct the cross correlation to a specified tolerance. More...

Protected Member Functions
void	findPeak (Scalar &xShift, Scalar &yShift)

Protected Attributes
int	m_maxLag {5}
	The maximum lag to consider in the initial cross-correlation. Default is 5. More...

Scalar	m_tol {0.1}
	The tolerance of the interpolated-magnified image, in pixels. More...

Scalar	m_magSize {0}
	Magnified size of the ccIm when using interp. Set as function of m_tol and m_maxLag. More...

Working Memory
ccImT	m_refIm
	The normalized reference image. More...

realT	m_refX0 {0}
	The shift of the reference image to itself, used as coordinate origint. More...

realT	m_refY0 {0}
	The shift of the reference image to itself, used as coordinate origint. More...

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

bool	m_haveMask {false}
	Flag indicating that a mask has been provided. More...

bool	m_normalize {true}

ccImT	m_normIm
	The normalized image. More...

ccImT	m_ccIm
	The cross-correlation image. More...

ccImT	m_magIm
	The magnified image, used if m_peakMethod == xcorrPeakMethod::interp. More...

complexArrayT	m_ftIm0
	Working memory for the FT of the reference image. More...

complexArrayT	m_ftWork
	Working memory for the FFT. More...

math::fft::fftT< realT, complexT, 2, 0 >	m_fft_fwd
	FFT object for the forward transform. More...

math::fft::fftT< complexT, realT, 2, 0 >	m_fft_back
	FFT object for the backward transfsorm. More...

Member Typedef Documentation

◆ ccImT

template<class _ccImT >

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

the Eigen-like array type used for image processing

Definition at line 71 of file imageXCorrFFT.hpp.

◆ complexArrayT

template<class _ccImT >

typedef Eigen::Array<complexT, Eigen::Dynamic, Eigen::Dynamic> mx::improc::imageXCorrFFT< _ccImT >::complexArrayT

Complex eigen array type with Scalar==complexT.

Definition at line 81 of file imageXCorrFFT.hpp.

◆ complexT

template<class _ccImT >

typedef std::complex<realT> mx::improc::imageXCorrFFT< _ccImT >::complexT

Complex floating point type.

Definition at line 77 of file imageXCorrFFT.hpp.

◆ realArrayT

template<class _ccImT >

typedef Eigen::Array<realT, Eigen::Dynamic, Eigen::Dynamic> mx::improc::imageXCorrFFT< _ccImT >::realArrayT

Real eigen array type.

Definition at line 79 of file imageXCorrFFT.hpp.

◆ realT

template<class _ccImT >

typedef _ccImT::Scalar mx::improc::imageXCorrFFT< _ccImT >::realT

the scalar type of the image type

Definition at line 75 of file imageXCorrFFT.hpp.

◆ Scalar

template<class _ccImT >

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

the scalar type of the image type

Definition at line 73 of file imageXCorrFFT.hpp.

Constructor & Destructor Documentation

◆ imageXCorrFFT() [1/2]

template<class ccImT >

mx::improc::imageXCorrFFT< ccImT >::imageXCorrFFT

Default c'tor.

Definition at line 264 of file imageXCorrFFT.hpp.

◆ imageXCorrFFT() [2/2]

template<class ccImT >

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

explicit

Constructor setting maxLag.

Definition at line 270 of file imageXCorrFFT.hpp.

Member Function Documentation

◆ ccIm()

template<class ccImT >

const ccImT & mx::improc::imageXCorrFFT< ccImT >::ccIm

Get a reference to the cross correlation image.

Returns: a const referent to m_ccIm.

Definition at line 461 of file imageXCorrFFT.hpp.

◆ findPeak()

template<class ccImT >

void mx::improc::imageXCorrFFT< ccImT >::findPeak	(	Scalar &	xShift,
		Scalar &	yShift
	)

protected

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

Definition at line 473 of file imageXCorrFFT.hpp.

◆ magIm()

template<class ccImT >

const ccImT & mx::improc::imageXCorrFFT< ccImT >::magIm

Get a reference to the magnified image.

Returns: a const referent to m_magIm.

Definition at line 467 of file imageXCorrFFT.hpp.

◆ maskIm() [1/2]

template<class ccImT >

const ccImT & mx::improc::imageXCorrFFT< ccImT >::maskIm

Get a reference to the mask image.

Returns: a const referance to the mask image.

Definition at line 381 of file imageXCorrFFT.hpp.

◆ maskIm() [2/2]

template<class ccImT >

int mx::improc::imageXCorrFFT< 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 372 of file imageXCorrFFT.hpp.

◆ maxLag() [1/2]

template<class ccImT >

int mx::improc::imageXCorrFFT< ccImT >::maxLag

Get the current maximum lag.

Returns: the current value of m_maxLag

Definition at line 316 of file imageXCorrFFT.hpp.

◆ maxLag() [2/2]

template<class ccImT >

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

Set the maximum lag.

Parameters

[in] ml the new maximum lag

Definition at line 322 of file imageXCorrFFT.hpp.

◆ normalize() [1/2]

template<class ccImT >

bool mx::improc::imageXCorrFFT< ccImT >::normalize

Get the current value of the normalize flag.

Returns: the current value of m_normalize

Definition at line 304 of file imageXCorrFFT.hpp.

◆ normalize() [2/2]

template<class ccImT >

void mx::improc::imageXCorrFFT< ccImT >::normalize ( bool no )

Set the normalize flag.

Todo:: check if this has side effects that should be triggered

Parameters

[in] no the new normalize flag value

Definition at line 310 of file imageXCorrFFT.hpp.

◆ normIm()

template<class ccImT >

const ccImT & mx::improc::imageXCorrFFT< ccImT >::normIm

Get a reference to the normalized image.

Returns: a const referent to m_normIm.

Definition at line 455 of file imageXCorrFFT.hpp.

◆ operator()() [1/2]

template<class ccImT >

template<class imT >

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

Conduct the cross correlation to a specified tolerance.

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 541 of file imageXCorrFFT.hpp.

References mx::improc::HCI::imageMean, and mx::improc::imageVariance().

◆ operator()() [2/2]

template<class ccImT >

template<class im0T , class imT >

int mx::improc::imageXCorrFFT< ccImT >::operator()	(	Scalar &	xShift,
		Scalar &	yShift,
		im0T &	im0,
		imT &	im
	)

Conduct the cross correlation to a specified tolerance.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

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]	im0	a new reference image
[in]	im	the image to cross-correlate with the reference

Definition at line 661 of file imageXCorrFFT.hpp.

◆ refIm() [1/2]

template<class ccImT >

const ccImT & mx::improc::imageXCorrFFT< ccImT >::refIm

Get a reference to the reference image.

Returns: a const referent to m_refIm.

Definition at line 449 of file imageXCorrFFT.hpp.

◆ refIm() [2/2]

template<class ccImT >

int mx::improc::imageXCorrFFT< 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. Then Fourier transform and conjugates the result.

Returns: 0 on success; -1 on error

Definition at line 387 of file imageXCorrFFT.hpp.

References mx::astro::constants::c(), mx::improc::HCI::imageMean, mx::improc::imageShiftWP(), and mx::improc::imageVariance().

◆ resize()

template<class ccImT >

int mx::improc::imageXCorrFFT< ccImT >::resize	(	int	nrows,
		int	ncols
	)

Set the size of the cross-correlation images.

This resizes all working memory and conducts fftw planning.

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

Definition at line 276 of file imageXCorrFFT.hpp.

◆ tol() [1/2]

template<class ccImT >

ccImT::Scalar mx::improc::imageXCorrFFT< ccImT >::tol

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

Returns: the current value of m_tol.

Definition at line 329 of file imageXCorrFFT.hpp.

◆ tol() [2/2]

template<class ccImT >

void mx::improc::imageXCorrFFT< 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 335 of file imageXCorrFFT.hpp.

Member Data Documentation

◆ m_ccIm

template<class _ccImT >

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

protected

The cross-correlation image.

Definition at line 107 of file imageXCorrFFT.hpp.

◆ m_fft_back

template<class _ccImT >

math::fft::fftT< complexT, realT,2,0> mx::improc::imageXCorrFFT< _ccImT >::m_fft_back

protected

FFT object for the backward transfsorm.

Definition at line 117 of file imageXCorrFFT.hpp.

◆ m_fft_fwd

template<class _ccImT >

math::fft::fftT< realT, complexT,2,0> mx::improc::imageXCorrFFT< _ccImT >::m_fft_fwd

protected

FFT object for the forward transform.

Definition at line 115 of file imageXCorrFFT.hpp.

◆ m_ftIm0

template<class _ccImT >

complexArrayT mx::improc::imageXCorrFFT< _ccImT >::m_ftIm0

protected

Working memory for the FT of the reference image.

Definition at line 111 of file imageXCorrFFT.hpp.

◆ m_ftWork

template<class _ccImT >

complexArrayT mx::improc::imageXCorrFFT< _ccImT >::m_ftWork

protected

Working memory for the FFT.

Definition at line 113 of file imageXCorrFFT.hpp.

◆ m_haveMask

template<class _ccImT >

bool mx::improc::imageXCorrFFT< _ccImT >::m_haveMask {false}

protected

Flag indicating that a mask has been provided.

Definition at line 101 of file imageXCorrFFT.hpp.

◆ m_magIm

template<class _ccImT >

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

protected

The magnified image, used if m_peakMethod == xcorrPeakMethod::interp.

Definition at line 109 of file imageXCorrFFT.hpp.

◆ m_magSize

template<class _ccImT >

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

protected

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

Definition at line 127 of file imageXCorrFFT.hpp.

◆ m_maskIm

template<class _ccImT >

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

protected

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

Definition at line 99 of file imageXCorrFFT.hpp.

◆ m_maxLag

template<class _ccImT >

int mx::improc::imageXCorrFFT< _ccImT >::m_maxLag {5}

protected

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

Definition at line 123 of file imageXCorrFFT.hpp.

◆ m_normIm

template<class _ccImT >

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

protected

The normalized image.

Definition at line 105 of file imageXCorrFFT.hpp.

◆ m_refIm

template<class _ccImT >

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

protected

The normalized reference image.

Definition at line 93 of file imageXCorrFFT.hpp.

◆ m_refX0

template<class _ccImT >

realT mx::improc::imageXCorrFFT< _ccImT >::m_refX0 {0}

protected

The shift of the reference image to itself, used as coordinate origint.

Definition at line 95 of file imageXCorrFFT.hpp.

◆ m_refY0

template<class _ccImT >

realT mx::improc::imageXCorrFFT< _ccImT >::m_refY0 {0}

protected

The shift of the reference image to itself, used as coordinate origint.

Definition at line 97 of file imageXCorrFFT.hpp.

◆ m_tol

template<class _ccImT >

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

protected

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

Definition at line 125 of file imageXCorrFFT.hpp.

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

improc/imageXCorrFFT.hpp

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

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Member Typedef Documentation

◆ ccImT

◆ complexArrayT

◆ complexT

◆ realArrayT

◆ realT

◆ Scalar

Constructor & Destructor Documentation

◆ imageXCorrFFT() [1/2]

◆ imageXCorrFFT() [2/2]

Member Function Documentation

◆ ccIm()

◆ findPeak()

◆ magIm()

◆ maskIm() [1/2]

◆ maskIm() [2/2]

◆ maxLag() [1/2]

◆ maxLag() [2/2]

◆ normalize() [1/2]

◆ normalize() [2/2]

◆ normIm()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ refIm() [1/2]

◆ refIm() [2/2]

◆ resize()

◆ tol() [1/2]

◆ tol() [2/2]

Member Data Documentation

◆ m_ccIm

◆ m_fft_back

◆ m_fft_fwd

◆ m_ftIm0

◆ m_ftWork

◆ m_haveMask

◆ m_magIm

◆ m_magSize

◆ m_maskIm

◆ m_maxLag

◆ m_normIm

◆ m_refIm

◆ m_refX0

◆ m_refY0

◆ m_tol

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