edu.mines.jtk.dsp
Class LocalCorrelationFilter

java.lang.Object
  edu.mines.jtk.dsp.LocalCorrelationFilter

public class LocalCorrelationFilter
extends java.lang.Object

Local cross-correlation of two arrays with seamless overlapping windows. Given two input arrays f and g and a specified lag, this filter computes an output array c of local cross-correlation coefficients, one for each sample in the input arrays f and g.

Two types of cross-correlation are implemented. Both types can be normalized to obtain cross-correlation coefficients with magnitudes that do not exceed one. The normalization varies, depending on the type of cross-correlation.

Simple cross-correlation computes an array of products h[j] = f[j]*g[j+lag] and then filters this array of products with a window. The resulting correlation cfg[k,lag] is not symmetric with respect to lag; cfg[k,-lag] = cgf[k-lag,lag] != cgf[k,lag]. For simple cross-correlation, normalization scale factors vary with lag and should be applied before picking correlation peaks.

Symmetric cross-correlation computes an array of products h[j] = f[j-lag/2]*g[j+lag/2] and therefore requires interpolation between samples for odd lags. (For efficiency, we interpolate the products h, not the inputs f and g.) The resulting correlation is symmetric with respect to lag; cfg[k,lag] = cgf[k,-lag]. Moreover, when inputs f and g are the same, each local auto-correlation has a Fourier transform (a power spectrum) that is positive-semidefinite. For symmetric cross-correlation, normalization scale factors do not vary with lag, and therefore need not be applied before picking correlation peaks.

Two correlation windows are implemented: Gaussian and rectangular. Gaussian windows should be used for most applications. Rectangular windows are provided primarily for comparison, because they are so often used by others.

Version:

2006.08.11

Author:

Dave Hale, Colorado School of Mines

Nested Class Summary

static class	LocalCorrelationFilter.Type Cross-correlations types.
static class	LocalCorrelationFilter.Window Cross-correlations windows.

Constructor Summary

LocalCorrelationFilter(LocalCorrelationFilter.Type type, LocalCorrelationFilter.Window window, double sigma)
Construct a correlation filter with specified parameters.

LocalCorrelationFilter(LocalCorrelationFilter.Type type, LocalCorrelationFilter.Window window, double sigma1, double sigma2)
Construct a correlation filter with specified parameters.

LocalCorrelationFilter(LocalCorrelationFilter.Type type, LocalCorrelationFilter.Window window, double sigma1, double sigma2, double sigma3)
Construct a correlation filter with specified parameters.

Method Summary

void	correlate(int lag, float[] c) Correlates the current inputs for the specified lag.
void	correlate(int lag1, int lag2, float[][] c) Correlates the current inputs for the specified lag.
void	correlate(int lag1, int lag2, int lag3, float[][][] c) Correlates the current inputs for the specified lag.
void	normalize(int lag, float[] c) Normalizes the cross-correlation for a specified lag.
void	normalize(int lag1, int lag2, float[][] c) Normalizes the cross-correlation for a specified lag.
void	normalize(int lag1, int lag2, int lag3, float[][][] c) Normalizes the cross-correlation for a specified lag.
void	setInputs(float[][][] f, float[][][] g) Sets the input arrays to be cross-correlated.
void	setInputs(float[][] f, float[][] g) Sets the input arrays to be cross-correlated.
void	setInputs(float[] f, float[] g) Sets the input arrays to be cross-correlated.
float[]	unbias(float[] f) Removes bias by subtracting local means from the specified array.
float[][]	unbias(float[][] f) Removes bias by subtracting local means from the specified array.
float[][][]	unbias(float[][][] f) Removes bias by subtracting local means from the specified array.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

LocalCorrelationFilter

public LocalCorrelationFilter(LocalCorrelationFilter.Type type,
                              LocalCorrelationFilter.Window window,
                              double sigma)

Construct a correlation filter with specified parameters. When applied to multi-dimensional arrays, the filter has the same half-width for all dimensions.

Parameters:

type - the correlation type.

window - the correlation window.

sigma - the correlation window half-width; must not be less than 1.

LocalCorrelationFilter

public LocalCorrelationFilter(LocalCorrelationFilter.Type type,
                              LocalCorrelationFilter.Window window,
                              double sigma1,
                              double sigma2)

Construct a correlation filter with specified parameters. When applied to multi-dimensional arrays, the filter has half-width sigma1 for the 1st dimension and half-width sigma2 for 2nd and higher dimensions.

Parameters:

type - the correlation type.

window - the correlation window.

sigma1 - correlation window half-width for 1st dimension; must not be less than 1.

sigma2 - correlation window half-width for 2nd and higher dimensions; must not be less than 1.

LocalCorrelationFilter

public LocalCorrelationFilter(LocalCorrelationFilter.Type type,
                              LocalCorrelationFilter.Window window,
                              double sigma1,
                              double sigma2,
                              double sigma3)

Construct a correlation filter with specified parameters. When applied to multi-dimensional arrays, the filter has half-width sigma1 for the 1st dimension, half-width sigma2 for the 2nd dimension, and half-width sigma3 for 3rd and higher dimensions.

Parameters:

type - the correlation type.

window - the correlation window.

sigma1 - correlation window half-width for 1st dimension; must not be less than 1.

sigma2 - correlation window half-width for 2nd dimension; must not be less than 1.

sigma3 - correlation window half-width for 3rd and higher dimensions; must not be less than 1.

Method Detail

setInputs

public void setInputs(float[] f,
                      float[] g)

Sets the input arrays to be cross-correlated. The input arrays f and g can be the same array.

Parameters:

f - the input array f; by reference, not copied.

g - the input array g; by reference, not copied.

setInputs

public void setInputs(float[][] f,
                      float[][] g)

Sets the input arrays to be cross-correlated. The input arrays f and g can be the same array.

Parameters:

f - the input array f; by reference, not copied.

g - the input array g; by reference, not copied.

setInputs

public void setInputs(float[][][] f,
                      float[][][] g)

Sets the input arrays to be cross-correlated. The input arrays f and g can be the same array.

Parameters:

f - the input array f; by reference, not copied.

g - the input array g; by reference, not copied.

correlate

public void correlate(int lag,
                      float[] c)

Correlates the current inputs for the specified lag.

Parameters:

lag - the correlation lag.

c - the output array; cannot be the same as inputs f or g.

correlate

public void correlate(int lag1,
                      int lag2,
                      float[][] c)

Correlates the current inputs for the specified lag.

Parameters:

lag1 - the lag in the 1st dimension.

lag2 - the lag in the 2nd dimension.

c - the output array; cannot be the same as inputs f or g.

correlate

public void correlate(int lag1,
                      int lag2,
                      int lag3,
                      float[][][] c)

Correlates the current inputs for the specified lag.

Parameters:

lag1 - the lag in the 1st dimension.

lag2 - the lag in the 2nd dimension.

lag3 - the lag in the 3rd dimension.

c - the output array; cannot be the same as inputs f or g.

normalize

public void normalize(int lag,
                      float[] c)

Normalizes the cross-correlation for a specified lag.

Parameters:

lag - the lag.

c - the cross-correlation to be modified.

normalize

public void normalize(int lag1,
                      int lag2,
                      float[][] c)

Normalizes the cross-correlation for a specified lag.

Parameters:

lag1 - the lag.

c - the cross-correlation to be modified.

normalize

public void normalize(int lag1,
                      int lag2,
                      int lag3,
                      float[][][] c)

Normalizes the cross-correlation for a specified lag.

Parameters:

lag1 - the lag in the 1st dimension.

lag2 - the lag in the 2nd dimension.

lag3 - the lag in the 3rd dimension.

c - the cross-correlation to be modified.

unbias

public float[] unbias(float[] f)

Removes bias by subtracting local means from the specified array.

Parameters:

f - the input array.

Returns:

the output array, with bias subtracted.

unbias

public float[][] unbias(float[][] f)

Removes bias by subtracting local means from the specified array.

Parameters:

f - the input array.

Returns:

the output array, with bias subtracted.

unbias

public float[][][] unbias(float[][][] f)

Removes bias by subtracting local means from the specified array.

Parameters:

f - the input array.

Returns:

the output array, with bias subtracted.