jwo.landserf.structure
Class Quadratic

java.lang.Object
  extended by jwo.landserf.structure.Quadratic

public class Quadratic
extends Object

Class for fitting a Quadratic surface through a local window of values. Uses least squares found through LU decomposition to calculate the 6 coefficients that represent the surface.

Version:
2.3, 4th May, 2007.
Author:
Jo Wood

Field Summary
static int CIRCULAR
          Circular elliptic section.
static int ELLIPTIC
          Elliptic conic section.
static int HORIZONTAL
          Horizontal, planar conic section.
static int HYPERBOLIC
          Hyperbolic conic section.
static int PARABOLIC
          Parabolic conic section.
static int PLANAR
          Sloping planar conic section.
 
Constructor Summary
Quadratic(float[] x, float[] y, float cx, float cy, float radius, double decayExp)
          Solves the best-fit quadratic surface for a given set of coordinates.
Quadratic(int wSize, float gSize)
          Creates the normal equations used to calculate the quadratic coefficients.
Quadratic(int wSize, float gSize, double decayExp)
          Creates the normal equations used to calculate the quadratic coefficients.
 
Method Summary
 FeatureAxis getChannelAxis()
          Reports the most channel like axis based on conic section analysis.
 float[] getCoeff(float[] zCoords)
          Returns the 6 quadratic coefficients for a given set of irregular points.
 float[] getCoeff(float[][] window)
          Returns the 6 quadratic coefficients a-f.
 float getCurveTol()
          Reports the curvature tolerance used in feature classification.
 double getFlowDirection()
          Reports the flow direction in radians anti-clockwise from N.
 float getGridSize()
          Reports the grid size (resolution) used to generate the quadratic patch.
 FeatureAxis[] getIntersections()
          Returns an array of axis objects containing the principal axes of any surface feature and the region of interest.
 float getMeanResidual(float[] coeff, float[][] window)
          Returns weighted Root Mean Squared residuals for a given set of quadratic coefficients and local window.
 float getPointConfidence()
          Reports the confidence of point classification (pits, peaks, passes).
 int getType(float[] coeff)
          Returns the type of conic section represented by the quadratic.
 double getXCentre()
          Returns the x coordinate of the point of inflection of the quadratic.
 double getYCentre()
          Returns the y coordinate of the point of inflection of the quadratic.
 float getZ(float[][] window, float xOffset, float yOffset)
          Reports the height at a given offset from the centre of the quadratic surface.
 float getZ(float[] coeff, float xOffset, float yOffset)
          Reports the height at a given offset from the centre of the quadratic surface.
 boolean isFlat(float[][] window)
          Reports whether the quadratic representing the given window represents a flat horizontal surface or not.
 void setCurveTol(float curveTol)
          Sets the curvature tolerance used in feature classification.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

HORIZONTAL

public static final int HORIZONTAL
Horizontal, planar conic section.

See Also:
Constant Field Values

PLANAR

public static final int PLANAR
Sloping planar conic section.

See Also:
Constant Field Values

PARABOLIC

public static final int PARABOLIC
Parabolic conic section.

See Also:
Constant Field Values

ELLIPTIC

public static final int ELLIPTIC
Elliptic conic section.

See Also:
Constant Field Values

CIRCULAR

public static final int CIRCULAR
Circular elliptic section.

See Also:
Constant Field Values

HYPERBOLIC

public static final int HYPERBOLIC
Hyperbolic conic section.

See Also:
Constant Field Values
Constructor Detail

Quadratic

public Quadratic(int wSize,
                 float gSize)
Creates the normal equations used to calculate the quadratic coefficients. These values remain constant for any single window size and distance decay function. Assumes no distance decay away from central cell.

Parameters:
wSize - Size of local window (odd only).
gSize - Size of 1 grid cell (resolution). Assumes square grid cells (x and y resolutions identical).

Quadratic

public Quadratic(int wSize,
                 float gSize,
                 double decayExp)
Creates the normal equations used to calculate the quadratic coefficients.

Parameters:
wSize - Size of local window (odd only).
gSize - Size of 1 grid cell (resolution). Assumes square grid cells (x and y resolutions identical).
decayExp - Distance decay exponent (0 no decay, 1 linear distance decay, 2 distance squared decay etc.)

Quadratic

public Quadratic(float[] x,
                 float[] y,
                 float cx,
                 float cy,
                 float radius,
                 double decayExp)
Solves the best-fit quadratic surface for a given set of coordinates. Must supply at least 6 coordinate triplets for the surface to be solved.

Parameters:
x - Array of at least 6 x coordinates.
y - Array of at least 6 y coordinates.
cx - x coordinate of centre point of function.
cy - y coordinate of centre point of function.
radius - Radius of interest for feature classification (equivalent to grid size for raster processing).
decayExp - Distance decay exponent(0 no decay, 1 linear distance decay, 2 distance squared decay etc.)
Method Detail

getCoeff

public float[] getCoeff(float[][] window)
Returns the 6 quadratic coefficients a-f. They represent, in order, the following equation: ax^2 + by^2 + cxy + dx +ey + f.

Parameters:
window - Array holding local window values.
Returns:
Vector containing the 6 quadratic coefficients a - f.

getCoeff

public float[] getCoeff(float[] zCoords)
Returns the 6 quadratic coefficients for a given set of irregular points. The list of z coordinates must match the x and y coordinates supplied when constructing this object and must contain at least 6 values.

Parameters:
zCoords - list of z coordinates defining surface heights.
Returns:
Vector containing the 6 quadratic coefficients.

getGridSize

public float getGridSize()
Reports the grid size (resolution) used to generate the quadratic patch.

Returns:
Grid size in geographic units.

getZ

public float getZ(float[][] window,
                  float xOffset,
                  float yOffset)
Reports the height at a given offset from the centre of the quadratic surface. Note that the coordinate system relative to the centre of the window and is dependent on the grid resolution. If this method needs to be called several times with different offsets but the same local window, consider calculating the coefficients once and calling the other getZ() method.

Parameters:
window - Array holding the local window values.
xOffset - Offset from the centre in the x direction.
yOffset - Offset from the centre in the y direction (positive values below the centre, negative values above.
Returns:
Height at given offset.

getZ

public float getZ(float[] coeff,
                  float xOffset,
                  float yOffset)
Reports the height at a given offset from the centre of the quadratic surface. Note that the coordinate system relative to the centre of the window and is dependent on the grid resolution. This version is suitable if several offsets are to supplied using the same coefficients.

Parameters:
coeff - Coefficients representing surface.
xOffset - Offset from the centre in the x direction.
yOffset - Offset from the centre in the y direction (positive values below the centre, negative values above.
Returns:
Height at given offset.

getMeanResidual

public float getMeanResidual(float[] coeff,
                             float[][] window)
Returns weighted Root Mean Squared residuals for a given set of quadratic coefficients and local window.

Parameters:
coeff - Array holding the 6 quadratic coefficients.
window - Array holding local window values.
Returns:
Weighted RMS quadratic residuals.

isFlat

public boolean isFlat(float[][] window)
Reports whether the quadratic representing the given window represents a flat horizontal surface or not. Flatness is influenced by the currently set curvature tolerance. If true, the quadratic is in the form z = f. To identify the form of non-flat quadratic, call getType() instead.

Parameters:
window - Array holding local window values.
Returns:
True if quadratic represents a flat horizontal surface.
See Also:
getType(float[])

getType

public int getType(float[] coeff)
Returns the type of conic section represented by the quadratic. This will be one of PARABOLIC, ELLIPTIC, or HYPERBOLIC, or one of the special cases, HORIZONTAL, PLANAR or CIRCULAR. For simple test to see if quadratic is horizontal and flat, call isFlat() instead.

Parameters:
coeff - Array holding the 6 quadratic coefficients.
Returns:
Type of conic section represented by the quadratic.
See Also:
isFlat(float[][])

getIntersections

public FeatureAxis[] getIntersections()
Returns an array of axis objects containing the principal axes of any surface feature and the region of interest. Contains between 0 and 2 axes depending on the surface feature. HORIZONTAL and CIRCULAR surfaces contain no intersections; PLANAR surfaces contain one (in the aspect direction); PARABOLIC surfaces contain one (along the channel/ridge axis); ELLIPTIC and HYPERBOLIC surfaces contain two (along the ridge and channel axes). Can only be called after a call to getType() has been made.

Returns:
Array of axis objects containing the principle object axes.
See Also:
FeatureAxis

getFlowDirection

public double getFlowDirection()
Reports the flow direction in radians anti-clockwise from N. Can only be called after a call to getType() has been made.

Returns:
Direction of lowest outflow in radians anti-clockwise from N or Double.NaN if conic section is horizontal, circular or undefined.

getChannelAxis

public FeatureAxis getChannelAxis()
Reports the most channel like axis based on conic section analysis.

Returns:
Most channel-like axis. Returns null if not defined.

getXCentre

public double getXCentre()
Returns the x coordinate of the point of inflection of the quadratic. Useful for identifying highest point of peaks, lowest of pits and centres of passes. Can only be called after a call to getType() has been made.

Returns:
x coordinate of the point of inflection.

getYCentre

public double getYCentre()
Returns the y coordinate of the point of inflection of the quadratic. Useful for identifying highest point of peaks, lowest of pits and centres of passes. Can only be called after a call to getType() has been made.

Returns:
y coordinate of the point of inflection.

getPointConfidence

public float getPointConfidence()
Reports the confidence of point classification (pits, peaks, passes). Confidence is based on the lowest intersection of the most ridge-like feature with the region of interest, and the similarly highest channel-like intersection. The greater these values the 'stronger' the feature is. Can only be called after a call to getType() has been made.

Returns:
Point classification confidence. Value is in elevation units or -Float.MAX_VALUE if not a point feature.

setCurveTol

public void setCurveTol(float curveTol)
Sets the curvature tolerance used in feature classification.

Parameters:
curveTol - New curvature tolerance (dimensionless).

getCurveTol

public float getCurveTol()
Reports the curvature tolerance used in feature classification.

Returns:
Curvature tolerance (dimensionless).


Copyright Jo Wood, 1996-2009, last modified, 17th April, 2009