uk.ac.starlink.table.join
Class CartesianMatchEngine

java.lang.Object
  |
  +--uk.ac.starlink.table.join.CartesianMatchEngine
All Implemented Interfaces:
MatchEngine
Direct Known Subclasses:
SphericalPolarMatchEngine

public class CartesianMatchEngine
extends Object
implements MatchEngine

A matching engine which can match points in an ndim-dimensional space. All tuples (coordinate vectors) submitted to it must be -element arrays of Number objects. Tuples are considered matching if they fall within an ellipsoid defined by a scalar or vector error parameter submitted at construction time.


Field Summary
static double CELL_SCALE
          Scaling factor determining the size of a grid cell as a multiple of the size of the matching error in each dimension.
 
Constructor Summary
CartesianMatchEngine(int ndim, double err)
          Constructs a matcher which matches points in an ndim-dimensional Cartesian space.
 
Method Summary
 Object[] getBins(Object[] tuple)
          Returns a set of Cell objects representing the cell in which this tuple falls and somr or all of its neighbouring ones.
 double[] getErrors()
          Returns an array containing the principle radii of an ellipsoid that determines whether two points match.
 DescribedValue[] getMatchParameters()
          Returns a set of DescribedValue objects whose values can be modified to modify the matching criteria.
 ValueInfo[] getTupleInfos()
          Returns a set of ValueInfo objects indicating what is required for the elements of each tuple.
 boolean matches(Object[] tuple1, Object[] tuple2)
          Matches two tuples if they represent the coordinates of nearby points.
 void setError(double error)
          Sets the maximum distance between two points that counts as a match.
 void setErrors(double[] errors)
          Sets the array containing the principle radii of an ellipsoid that determines whether two points match.
 String toString()
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

CELL_SCALE

public static final double CELL_SCALE
Scaling factor determining the size of a grid cell as a multiple of the size of the matching error in each dimension. It can be used as a tuning parameter. It must be >=1.

See Also:
Constant Field Values
Constructor Detail

CartesianMatchEngine

public CartesianMatchEngine(int ndim,
                            double err)
Constructs a matcher which matches points in an ndim-dimensional Cartesian space. An initial isotropic error margin is specified.

Parameters:
ndim - dimensionality of the space
err - initial maximum distance between two matching points
Method Detail

matches

public boolean matches(Object[] tuple1,
                       Object[] tuple2)
Matches two tuples if they represent the coordinates of nearby points.

Specified by:
matches in interface MatchEngine
Parameters:
tuple1 - ndim-element array of Number objects representing coordinates of first object
tuple2 - ndim-element array of Number objects representing coordinates of second object
Returns:
true if tuple1 and tuple2 fall within the same error ellipsoid

getBins

public Object[] getBins(Object[] tuple)
Returns a set of Cell objects representing the cell in which this tuple falls and somr or all of its neighbouring ones.

Specified by:
getBins in interface MatchEngine
Parameters:
tuple - ndim-element array of Number objects representing coordinates of an object
Returns:
set of bin keys which might be returned by invoking this method on other tuples which count as matches for the submitted tuple

getTupleInfos

public ValueInfo[] getTupleInfos()
Description copied from interface: MatchEngine
Returns a set of ValueInfo objects indicating what is required for the elements of each tuple. The length of this array is the number of elements in the tuple. Each element should at least have a defined name and content class. The info's nullable attribute has a special meaning: if true it means that it makes sense for this element of the tuple to be always blank (for instance assigned to no column).

Specified by:
getTupleInfos in interface MatchEngine
Returns:
array of objects describing the requirements on each element of the tuples used for matching

getMatchParameters

public DescribedValue[] getMatchParameters()
Description copied from interface: MatchEngine
Returns a set of DescribedValue objects whose values can be modified to modify the matching criteria. Typically at least one of these will be some sort of tolerance separation which determines how close tuples must be to count as a match. This match engine's behaviour can be modified by calling DescribedValue.setValue(java.lang.Object) on the returned objects.

Specified by:
getMatchParameters in interface MatchEngine
Returns:
array of described values which influence the match

getErrors

public double[] getErrors()
Returns an array containing the principle radii of an ellipsoid that determines whether two points match. The returned array is a clone of the internal data structure; use setErrors to change the values.

Returns:
error array

setErrors

public void setErrors(double[] errors)
Sets the array containing the principle radii of an ellipsoid that determines whether two points match.

Note you should not set anisotropic errors (not all elements having the same value) if you are using the Separation parameter, since that is currently defined as a scalar; doing so this may result in an unwelcome unchecked error.

Parameters:
errors - error array

setError

public void setError(double error)
Sets the maximum distance between two points that counts as a match. This is equivalent to setting the value of the Error parameter.

Parameters:
error - maximum distance for matching

toString

public String toString()
Overrides:
toString in class Object

Copyright © 2004 CLRC: Central Laboratory of the Research Councils. All rights reserved.