edu.mines.jtk.dsp
Class LocalOrientFilter

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

public class LocalOrientFilter
extends java.lang.Object

Local estimates of orientations of features in images. Methods of this class can compute for each image sample numerous parameters related to orientation. All orientation information is derived from eigenvectors and eigenvalues of the structure tensor (also called the "gradient-squared tensor"). This tensor is equivalent to a matrix of 2nd partial derivatives of an autocorrelation evaluated at zero lag. In other words, orientation is here determined by the (2-D) ellipse or (3-D) ellipsoid that best fits the peak of the autocorrelation of image samples in a local window.

The coordinate system for a 2-D image has two orthogonal axes 1 and 2, which correspond to the 1st and 2nd indices of the array containing image samples. For 2-D images, the eigenvectors are the unit vectors u = (u1,u2) and v = (v1,v2). The 1st eigenvector u is perpendicular to the best fitting line, and the 1st component u1 of u is always non-negative. The 2nd eigenvector v is perpendicular to u such that the cross product u1*v2-u2*v1 = 1; that is, v1 = -u2 and v2 = u1. The angle theta = asin(u2) is the angle measured counter-clockwise between the 1st eigenvector u and axis 1; -pi/2 <= theta <= pi/2.

The coordinate system for a 3-D image has three orthogonal axes 1, 2 and 3, which correspond to the 1st, 2nd and 3rd indices of the array containing image samples. For 3-D images, the eigenvectors are unit vectors u = (u1,u2,u3), v = (v1,v2,v3), and w = (w1,w2,w3). The 1st eigenvector u is orthogonal to the best fitting plane, and the 1st component u1 of u is always non-negative. The 2nd eigenvector v is orthogonal to the best fitting line within the best fitting plane. The 3rd eigenvector w is orthogonal to both u and v and is aligned with the direction in which the images changes least. The dip angle theta = acos(u1) is the angle between the 1st eigenvector u and axis 1; 0 <= theta <= pi/2. The azimuthal angle phi = atan2(u3,u2) is well-defined for only non-zero theta; -pi <= phi <= pi.

The local linearity or planarity of features is determined by the eigenvalues. For 2-D images with eigenvalues eu and ev (corresponding to the eigenvectors u and v), linearity is (eu-ev)/eu. For 3-D images with eigenvalues eu, ev, and ew, planarity is (eu-ev)/eu and linearity is (ev-ew)/eu. Both linearity and planarity are in the range [0,1].

Version:

2007.02.12

Author:

Dave Hale, Colorado School of Mines

Constructor Summary

LocalOrientFilter(double sigma)
Constructs a filter with an isotropic Gaussian window.

LocalOrientFilter(double sigma1, double sigma2)
Constructs a filter with a possibly anisotropic Gaussian window.

LocalOrientFilter(double sigma1, double sigma2, double sigma3)
Constructs a filter with a possibly anisotropic Gaussian window.

Method Summary

void	apply(float[][][] x, float[][][] theta, float[][][] phi, float[][][] u1, float[][][] u2, float[][][] u3, float[][][] v1, float[][][] v2, float[][][] v3, float[][][] w1, float[][][] w2, float[][][] w3, float[][][] eu, float[][][] ev, float[][][] ew, float[][][] ep, float[][][] el) Applies this filter for the specified image and outputs.
void	apply(float[][] x, float[][] theta, float[][] u1, float[][] u2, float[][] v1, float[][] v2, float[][] eu, float[][] ev, float[][] el) Applies this filter for the specified image and outputs.
void	applyForInline(float[][][] x, float[][][] w1, float[][][] w2, float[][][] w3) Applies this filter to estimate inline vectors (3rd eigenvectors).
void	applyForInlineLinear(float[][][] x, float[][][] w1, float[][][] w2, float[][][] w3, float[][][] el) Applies this filter to estimate inline vectors and linearities.
void	applyForNormal(float[][][] x, float[][][] u1, float[][][] u2, float[][][] u3) Applies this filter to estimate normal vectors (1st eigenvectors).
void	applyForNormal(float[][] x, float[][] u1, float[][] u2) Applies this filter to estimate normal vectors (1st eigenvectors).
void	applyForNormalLinear(float[][] x, float[][] u1, float[][] u2, float[][] el) Applies this filter to estimate normal vectors and linearities.
void	applyForNormalPlanar(float[][][] x, float[][][] u1, float[][][] u2, float[][][] u3, float[][][] ep) Applies this filter to estimate normal vectors and planarities.
EigenTensors2	applyForTensors(float[][] x) Applies this filter to estimate 2-D structure tensors.
EigenTensors3	applyForTensors(float[][][] x) Applies this filter to estimate compressed 3-D structure tensors.
EigenTensors3	applyForTensors(float[][][] x, boolean compressed) Applies this filter to estimate 3-D structure tensors.
void	applyForTheta(float[][] x, float[][] theta) Applies this filter to estimate orientation angles.
void	applyForThetaPhi(float[][][] x, float[][][] theta, float[][][] phi) Applies this filter to estimate orientation angles.
void	setGradientSmoothing(double sigma) Sets half-width of Gaussian derivative filter used to compute gradients.
void	setGradientSmoothing(double sigma1, double sigma2) Sets half-widths of Gaussian derivative filters used to compute gradients.
void	setGradientSmoothing(double sigma1, double sigma2, double sigma3) Sets half-widths of Gaussian derivative filters used to compute gradients.

Methods inherited from class java.lang.Object

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

Constructor Detail

LocalOrientFilter

public LocalOrientFilter(double sigma)

Constructs a filter with an isotropic Gaussian window.

Parameters:

sigma - half-width of window; same for all dimensions.

LocalOrientFilter

public LocalOrientFilter(double sigma1,
                         double sigma2)

Constructs a filter with a possibly anisotropic Gaussian window.

Parameters:

sigma1 - half-width of window in 1st dimension.

sigma2 - half-width of window in 2nd and higher dimensions.

LocalOrientFilter

public LocalOrientFilter(double sigma1,
                         double sigma2,
                         double sigma3)

Constructs a filter with a possibly anisotropic Gaussian window.

Parameters:

sigma1 - half-width of window in 1st dimension.

sigma2 - half-width of window in 2nd dimension.

sigma3 - half-width of window in 3rd and higher dimensions.

Method Detail

setGradientSmoothing

public void setGradientSmoothing(double sigma)

Sets half-width of Gaussian derivative filter used to compute gradients. Typically, this half-width should not exceed one-fourth that of the the corresponding Gaussian window used to compute local averages of gradient products. The default half-width for Gaussian derivatives is 1.0.

Parameters:

sigma - half-width of derivatives; same for all dimensions.

setGradientSmoothing

public void setGradientSmoothing(double sigma1,
                                 double sigma2)

Sets half-widths of Gaussian derivative filters used to compute gradients. Typically, these half-widths should not exceed one-fourth those of the the corresponding Gaussian windows used to compute local averages of gradient-squared tensors. The default half-widths for Gaussian derivatives is 1.0.

Parameters:

sigma1 - half-width of derivative in 1st dimension.

sigma2 - half-width of derivatives in 2nd and higher dimensions.

setGradientSmoothing

public void setGradientSmoothing(double sigma1,
                                 double sigma2,
                                 double sigma3)

Sets half-widths of Gaussian derivative filters used to compute gradients. Typically, these half-widths should not exceed one-fourth those of the the corresponding Gaussian windows used to compute local averages of gradient-squared tensors. The default half-widths for Gaussian derivatives is 1.0.

Parameters:

sigma1 - half-width of derivative in 1st dimension.

sigma2 - half-width of derivative in 2nd dimension.

sigma3 - half-width of derivatives in 3rd and higher dimensions.

applyForTheta

public void applyForTheta(float[][] x,
                          float[][] theta)

Applies this filter to estimate orientation angles.

Parameters:

x - input array for 2-D image.

theta - orientation angle; -pi <= theta <= pi

applyForNormal

public void applyForNormal(float[][] x,
                           float[][] u1,
                           float[][] u2)

Applies this filter to estimate normal vectors (1st eigenvectors).

Parameters:

x - input array for 2-D image.

u1 - 1st component of normal vector.

u2 - 2nd component of normal vector.

applyForNormalLinear

public void applyForNormalLinear(float[][] x,
                                 float[][] u1,
                                 float[][] u2,
                                 float[][] el)

Applies this filter to estimate normal vectors and linearities.

Parameters:

x - input array for 2-D image.

u1 - 1st component of normal vector.

u2 - 2nd component of normal vector.

el - linearity in range [0,1].

applyForTensors

public EigenTensors2 applyForTensors(float[][] x)

Applies this filter to estimate 2-D structure tensors.

Parameters:

x - input array for 2-D image.

Returns:

structure tensors.

apply

public void apply(float[][] x,
                  float[][] theta,
                  float[][] u1,
                  float[][] u2,
                  float[][] v1,
                  float[][] v2,
                  float[][] eu,
                  float[][] ev,
                  float[][] el)

Applies this filter for the specified image and outputs. All outputs are optional and are computed for only non-null arrays.

Parameters:

x - input array for 2-D image

theta - orientation angle = asin(u2); -pi <= theta <= pi

u1 - 1st component of 1st eigenvector.

u2 - 2nd component of 1st eigenvector.

v1 - 1st component of 2nd eigenvector.

v2 - 2nd component of 2nd eigenvector.

eu - largest eigenvalue corresponding to the eigenvector u.

ev - smallest eigenvalue corresponding to the eigenvector v.

el - (eu-ev)/eu, a measure of linearity.

applyForThetaPhi

public void applyForThetaPhi(float[][][] x,
                             float[][][] theta,
                             float[][][] phi)

Applies this filter to estimate orientation angles.

Parameters:

x - input array for 3-D image.

theta - orientation dip angle; 0 <= theta <= pi/2.

phi - orientation azimuthal angle; -pi <= phi <= pi.

applyForNormal

public void applyForNormal(float[][][] x,
                           float[][][] u1,
                           float[][][] u2,
                           float[][][] u3)

Applies this filter to estimate normal vectors (1st eigenvectors).

Parameters:

x - input array for 3-D image.

u1 - 1st component of normal vector.

u2 - 2nd component of normal vector.

u3 - 3rd component of normal vector.

applyForNormalPlanar

public void applyForNormalPlanar(float[][][] x,
                                 float[][][] u1,
                                 float[][][] u2,
                                 float[][][] u3,
                                 float[][][] ep)

Applies this filter to estimate normal vectors and planarities. Normal vectors are 1st eigenvectors corresponding to largest eigenvalues.

Parameters:

x - input array for 3-D image.

u1 - 1st component of normal vector.

u2 - 2nd component of normal vector.

u3 - 3rd component of normal vector.

ep - planarity in range [0,1].

applyForInline

public void applyForInline(float[][][] x,
                           float[][][] w1,
                           float[][][] w2,
                           float[][][] w3)

Applies this filter to estimate inline vectors (3rd eigenvectors).

Parameters:

x - input array for 3-D image.

w1 - 1st component of inline vector.

w2 - 2nd component of inline vector.

w3 - 3rd component of inline vector.

applyForInlineLinear

public void applyForInlineLinear(float[][][] x,
                                 float[][][] w1,
                                 float[][][] w2,
                                 float[][][] w3,
                                 float[][][] el)

Applies this filter to estimate inline vectors and linearities. Inline vectors are 3rd eigenvectors corresponding to smallest eigenvalues.

Parameters:

x - input array for 3-D image.

w1 - 1st component of inline vector.

w2 - 2nd component of inline vector.

w3 - 3rd component of inline vector.

el - linearity in range [0,1].

applyForTensors

public EigenTensors3 applyForTensors(float[][][] x)

Applies this filter to estimate compressed 3-D structure tensors.

Parameters:

x - input array for 3-D image.

Returns:

structure tensors.

applyForTensors

public EigenTensors3 applyForTensors(float[][][] x,
                                     boolean compressed)

Applies this filter to estimate 3-D structure tensors.

Parameters:

x - input array for 3-D image.

compressed - true, for compressed tensors; false, otherwise.

Returns:

structure tensors.

apply

public void apply(float[][][] x,
                  float[][][] theta,
                  float[][][] phi,
                  float[][][] u1,
                  float[][][] u2,
                  float[][][] u3,
                  float[][][] v1,
                  float[][][] v2,
                  float[][][] v3,
                  float[][][] w1,
                  float[][][] w2,
                  float[][][] w3,
                  float[][][] eu,
                  float[][][] ev,
                  float[][][] ew,
                  float[][][] ep,
                  float[][][] el)

Applies this filter for the specified image and outputs. All outputs are optional and are computed for only non-null arrays.

Parameters:

x - input array for 3-D image.

theta - orientation dip angle; 0 <= theta <= pi/2.

phi - orientation azimuthal angle; -pi <= phi <= pi.

u1 - 1st component of 1st eigenvector.

u2 - 2nd component of 1st eigenvector.

u3 - 3rd component of 1st eigenvector.

v1 - 1st component of 2nd eigenvector.

v2 - 2nd component of 2nd eigenvector.

v3 - 3rd component of 2nd eigenvector.

w1 - 1st component of 3rd eigenvector.

w2 - 2nd component of 3rd eigenvector.

w3 - 3rd component of 3rd eigenvector.

eu - largest eigenvalue corresponding to the eigenvector u.

ev - middle eigenvalue corresponding to the eigenvector v.

ew - smallest eigenvalue corresponding to the eigenvector w.

ep - (eu-ev)/eu, a measure of planarity.

el - (ev-ew)/eu, a measure of linearity.