Package uk.ac.starlink.table.join

## Class AbstractCartesianMatchEngine

- java.lang.Object
- - uk.ac.starlink.table.join.AbstractCartesianMatchEngine

- All Implemented Interfaces:
    `MatchEngine`
  Direct Known Subclasses:
    `AnisotropicCartesianMatchEngine`, `CuboidCartesianMatchEngine`, `EllipseCartesianMatchEngine`, `ErrorCartesianMatchEngine`, `IsotropicCartesianMatchEngine`, `SphericalPolarMatchEngine`

      public abstract class AbstractCartesianMatchEngine
      extends java.lang.Object
      implements MatchEngine

  Abstract superclass for match engines working in a Cartesian space.
  Since:
    2 Sep 2011
  Author:
    Mark Taylor

- - ### Field Summary

    - ### Fields inherited from interface uk.ac.starlink.table.join.MatchEngine

      `NO_BINS`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `AbstractCartesianMatchEngine​(int ndim)` | Constructor.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `double` | `getBinFactor()` | Returns the multiplier for length scale that determines bin size.
    `double` | `getIsotropicScale()` | Returns the isotropic scale.
    `int` | `getNdim()` | Returns the dimensionality of the Cartesian space in which this match engine works.
    `protected java.lang.Object[]` | `getRadiusBins​(double[] coords, double radius)` | Returns an array of the bin objects that may be covered within a given distance of a given position.
    `protected double` | `getScale​(int idim)` | Returns the scale value for a given dimension.
    `protected java.lang.Object[]` | `getScaleBins​(double[] coords)` | Returns an array of the bin objects that may be covered within the current anisotropic scale length in each direction of a given position.
    `uk.ac.starlink.table.DescribedValue[]` | `getTuningParameters()` | Returns a set of DescribedValue objects whose values can be modified to tune the performance of the match.
    `void` | `setBinFactor​(double binFactor)` | Sets a multiplier for the length scale that determines bin size.
    `void` | `setIsotropicScale​(double scale)` | Sets the scale isotropically.
    `protected void` | `setScale​(int idim, double scale)` | Sets the scale value for a given dimension.
    `abstract java.lang.String` | `toString()` |

    - ### Methods inherited from class java.lang.Object

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

    - ### Methods inherited from interface uk.ac.starlink.table.join.MatchEngine

      `canBoundMatch, getBins, getMatchBounds, getMatchParameters, getMatchScoreInfo, getScoreScale, getTupleInfos, matchScore`

- - ### Constructor Detail

    - #### AbstractCartesianMatchEngine

          public AbstractCartesianMatchEngine​(int ndim)

      Constructor.
      Parameters:
        `ndim` - dimensionality of Cartesian space

  - ### Method Detail

    - #### getNdim

          public int getNdim()

      Returns the dimensionality of the Cartesian space in which this match engine works.
      Returns:
        number of spatial dimensions

    - #### setBinFactor

          public void setBinFactor​(double binFactor)

      Sets a multiplier for the length scale that determines bin size.
      Parameters:
        `binFactor` - bin size multiplier

    - #### getBinFactor

          public double getBinFactor()

      Returns the multiplier for length scale that determines bin size.
      Returns:
        bin size multiplier

    - #### setIsotropicScale

          public void setIsotropicScale​(double scale)

      Sets the scale isotropically. All dimension scales are set to the given value.
      Parameters:
        `scale` - guide error distance

    - #### getIsotropicScale

          public double getIsotropicScale()

      Returns the isotropic scale. If all dimension scales are set to the same value, that value is returned. If they are not all set to the same value, the return value is undefined.
      Returns:
        scale isotropic guide error distance

    - #### setScale

          protected void setScale​(int idim,
                                  double scale)

      Sets the scale value for a given dimension. In conjunction with the bin factor, this determines the bin size.
      Parameters:
        `idim` - dimension index
        `scale` - guide error distance in dimension `idim`

    - #### getScale

          protected double getScale​(int idim)

      Returns the scale value for a given dimension.
      Parameters:
        `idim` - dimension index
      Returns:
        guide error distance in dimension `idim`

    - #### getTuningParameters

          public uk.ac.starlink.table.DescribedValue[] getTuningParameters()

      Description copied from interface: `MatchEngine`
      Returns a set of DescribedValue objects whose values can be modified to tune the performance of the match. This match engine's performance can be influenced by calling `DescribedValue.setValue(java.lang.Object)` on the returned objects.

      Changing these values will make no difference to the output of `MatchEngine.matchScore(java.lang.Object[], java.lang.Object[])`, but may change the output of `MatchEngine.getBins(java.lang.Object[])`. This may change the CPU and memory requirements of the match, but will not change the result. The default value should be something sensible, so that setting the value of these parameters is not in general required.

      Specified by:
        `getTuningParameters` in interface `MatchEngine`
      Returns:
        array of described values which may influence match performance

    - #### getRadiusBins

          protected java.lang.Object[] getRadiusBins​(double[] coords,
                                                     double radius)

      Returns an array of the bin objects that may be covered within a given distance of a given position. Not all returned bins are guaranteed to be so covered. Validation is performed on the arguments (NaNs will result in an empty return).
      Parameters:
        `coords` - central position
        `radius` - error radius
      Returns:
        bin objects that may be within `radius` of `coords`

    - #### getScaleBins

          protected java.lang.Object[] getScaleBins​(double[] coords)

      Returns an array of the bin objects that may be covered within the current anisotropic scale length in each direction of a given position. Not all returned bins are guaranteed to be so covered. Validation is performed on the arguments (NaNs will result in an empty return.
      Parameters:
        `coords` - central position
      Returns:
        bin objects within a scale length of `coords`

    - #### toString

          public abstract java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`