Package uk.ac.starlink.topcat.plot2

## Class CoordSpotter

- java.lang.Object
- - uk.ac.starlink.topcat.plot2.CoordSpotter

-     public abstract class CoordSpotter
      extends java.lang.Object

  Defines criteria for identifying a matching tuple of coordinates from a list of ValueInfos.

  Some implementations are also provided. They are not bulletproof (what they are trying to do is really an AI task) but will probably do the right thing often enough to be useful rather than annoying.

  Since:
    11 Mar 2019
  Author:
    Mark Taylor

- - ### Constructor Summary

    Constructors
    Modifier | Constructor | Description
    --- | --- | ---
    `protected` | `CoordSpotter​(int ntype)` | Constructor.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static CoordSpotter` | `createNamePrefixSpotter​(java.lang.String[] alphaPrefixes, boolean isPrefix)` | Returns a CoordSpotter instance that looks at info name prefixes or suffixes.
    `static CoordSpotter` | `createUcdSpotter​(java.lang.String root, java.lang.String[] tails, boolean allowSuffix)` | Returns a CoordSpotter instance that looks at UCDs.
    `uk.ac.starlink.table.ValueInfo[]` | `findCoordGroups​(int npos, uk.ac.starlink.table.ValueInfo[] infos)` | Tries to find a number of, ideally matching, entries in a list of ValueInfos that corresponds to a fixed number of coordinate tuples, using this spotter's coordinate identification criteria.
    `static uk.ac.starlink.table.ValueInfo[]` | `findCoordGroups​(int npos, uk.ac.starlink.table.ValueInfo[] infos, CoordSpotter[] spotters)` | Tries to find a number of, ideally matching, entries in a list of ValueInfos that corresponds to a fixed number of coordinate tuples, using this coordinate identification criteria from a number of different spotter instances.
    `abstract int` | `getCoordType​(uk.ac.starlink.table.ValueInfo info)` | Returns an index indicating which coordinate type known by this spotter, if any, the given value info corresponds to.
    `int` | `getTypeCount()` | Returns the number of entries in the tuples found by this object.

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

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

- - ### Constructor Detail

    - #### CoordSpotter

          protected CoordSpotter​(int ntype)

      Constructor.
      Parameters:
        `ntype` - number of entries per tuple

  - ### Method Detail

    - #### getTypeCount

          public int getTypeCount()

      Returns the number of entries in the tuples found by this object.
      Returns:
        number of different coordinate types that can be identified

    - #### getCoordType

          public abstract int getCoordType​(uk.ac.starlink.table.ValueInfo info)

      Returns an index indicating which coordinate type known by this spotter, if any, the given value info corresponds to. If it doesn't look like one of the coordinates this object knows about, a negative value is returned.
      Parameters:
        `info` - metadata item to test
      Returns:
        integer from 0 to `ntype` if info is recognised, -1 if not

    - #### findCoordGroups

          public uk.ac.starlink.table.ValueInfo[] findCoordGroups​(int npos,
                                                                  uk.ac.starlink.table.ValueInfo[] infos)

      Tries to find a number of, ideally matching, entries in a list of ValueInfos that corresponds to a fixed number of coordinate tuples, using this spotter's coordinate identification criteria.
      Parameters:
        `npos` - number of tuples required
        `infos` - list of available metadata items
      Returns:
        if successful, an npos*ntype-element array giving (a1,b1,...a2,b2,..aN,bN), or null on failure

    - #### findCoordGroups

          public static uk.ac.starlink.table.ValueInfo[] findCoordGroups​(int npos,
                                                                         uk.ac.starlink.table.ValueInfo[] infos,
                                                                         CoordSpotter[] spotters)

      Tries to find a number of, ideally matching, entries in a list of ValueInfos that corresponds to a fixed number of coordinate tuples, using this coordinate identification criteria from a number of different spotter instances. Each one is tried in turn until one succeeds.
      Parameters:
        `npos` - number of tuples required
        `infos` - list of available metadata items
        `spotters` - list of spotter implementations to try
      Returns:
        if successful, an npos*ntype-element array giving (a1,b1,...a2,b2,..aN,bN), or null on failure

    - #### createNamePrefixSpotter

          public static CoordSpotter createNamePrefixSpotter​(java.lang.String[] alphaPrefixes,
                                                             boolean isPrefix)

      Returns a CoordSpotter instance that looks at info name prefixes or suffixes. The supplied pre/suffixes must be strictly alphabetic, since non-alphabetic characters are used as word boundaries.
      Parameters:
        `alphaPrefixes` - list of case-insensitive alphabetic column name prefixes/suffixes, one to identify each element of a coordinate group tuple
        `isPrefix` - true to look for prefixes, false for suffixes
      Returns:
        new spotter

    - #### createUcdSpotter

          public static CoordSpotter createUcdSpotter​(java.lang.String root,
                                                      java.lang.String[] tails,
                                                      boolean allowSuffix)

      Returns a CoordSpotter instance that looks at UCDs.
      Parameters:
        `root` - UCD root (do not include trailing ".")
        `tails` - list of strings to append to the root+"." to make a UCD for each tuple element to be identified
        `allowSuffix` - if false, UCD matching must be exact (apart from case); if true, trailing text after the matched part is allowed