# Class AuxScale

java.lang.Object
uk.ac.starlink.ttools.plot2.AuxScale

public class AuxScale extends Object
Represents a ranged value that can differ according to the content of a plot. To calculate the range of an AuxScale it is not necessary to have detailed information about the geometry of the plot surface (the Surface object required for final plotting). That means it is not required to generate the actual plot surface geometry. However, an approximate plot surface may be required for range calculations.

Since:
  4 Feb 2013
Author:
  Mark Taylor

## Field Summary

Fields
Modifier and Type
Field
Description
`static AuxScale`
`COLOR`
AuxScale object used for the standard colour scaling axis.

## Constructor Summary

Constructors
Constructor
Description
`AuxScale(String name)`
Constructor.

## Method Summary

Modifier and Type
Method
Description
`static Map<AuxScale,Span>`
`calculateAuxSpans(AuxScale[] scales, List<uk.ac.starlink.util.Bi<Surface, PlotLayer>> surfLayers, Object[] knownPlans, DataStore dataStore)`
Fills in range information for a submitted list of AuxScale objects from the data in a given list of layers.
`static Span`
`calculateSpan(AuxScale scale, List<uk.ac.starlink.util.Bi<Surface, PlotLayer>> surfLayers, Object[] knownPlans, DataStore dataStore)`
Calculates range information for an AuxScale object from the data in a given list of layers.
`static Span`
`clipSpan(Span dataSpan, Span fixSpan, Subrange subrange, boolean isLog)`
Amalgamates range requirements for a single scale to return the actual range to use.
`static AuxScale[]`
`getAuxScales(PlotLayer[] layers)`
Utility method to acquire all the scales that are used in an array of layers.
`static Set<AuxScale>`
`getMissingScales(PlotLayer[] layers, Map<AuxScale,Span> dataSpans, Map<AuxScale,Span> fixSpans)`
Returns a list of scale objects for which calculations are required.
`String`
`getName()`
Returns the scale name.
`static List<uk.ac.starlink.util.Bi<Surface, PlotLayer>>`
`pairSurfaceLayers(Surface surf, PlotLayer[] layers)`
Utility method that produces a list of paired (surface,layer) objects from an array of PlotLayers and a single Surface.
`String`
`toString()`

### Methods inherited from class Object

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

## Field Details

### COLOR

public static AuxScale COLOR
AuxScale object used for the standard colour scaling axis.

## Constructor Details

### AuxScale

public AuxScale(String name)
Constructor.

Parameters:
  `name` - scale name for human consumption

## Method Details

### getName

public String getName()
Returns the scale name.

Returns:
  name

### toString

public String toString()

Overrides:
  `toString` in class `Object`

### pairSurfaceLayers

public static List<uk.ac.starlink.util.Bi<Surface, PlotLayer>> pairSurfaceLayers(Surface surf, PlotLayer[] layers)
Utility method that produces a list of paired (surface,layer) objects from an array of PlotLayers and a single Surface.

Parameters:
  `surf` - surface common to all layers
  `layers` - plot layer array
Returns:
  list of pairs

### getAuxScales

public static AuxScale[] getAuxScales(PlotLayer[] layers)
Utility method to acquire all the scales that are used in an array of layers. The result is unordered and contains each scale only once (like a Set).

Parameters:
  `layers` - layers that may reference scales
Returns:
  array of uses scales

### calculateAuxSpans

public static Map<AuxScale,Span> calculateAuxSpans(AuxScale[] scales, List<uk.ac.starlink.util.Bi<Surface, PlotLayer>> surfLayers, Object[] knownPlans, DataStore dataStore)
Fills in range information for a submitted list of AuxScale objects from the data in a given list of layers. The supplied plot surface may be used to assess marker shape etc. It should have approximately the same behaviour as the surface on which the plot will take place, but it is usually not critical that it behaves identically.

Parameters:
  `scales` - scales to calculate ranges for
  `surfLayers` - list (layer, approximate surface) pairs over which spans should be calculated
  `knownPlans` - array of available plan objects; may be empty
  `dataStore` - data repository
Returns:
  map with a range entry for each of the `scales`

### calculateSpan

@Slow public static Span calculateSpan(AuxScale scale, List<uk.ac.starlink.util.Bi<Surface, PlotLayer>> surfLayers, Object[] knownPlans, DataStore dataStore)
Calculates range information for an AuxScale object from the data in a given list of layers.

Parameters:
  `scale` - scale to calculate ranges for
  `surfLayers` - list (layer, approximate surface) pairs over which spans should be calculated
  `knownPlans` - array of available plan objects; may be empty
  `dataStore` - data repository
Returns:
  span for `scale`

### clipSpan

public static Span clipSpan(Span dataSpan, Span fixSpan, Subrange subrange, boolean isLog)
Amalgamates range requirements for a single scale to return the actual range to use. Any or all of the arguments may be null.

Parameters:
  `dataSpan` - actual data span acquired by scanning the data, or null
  `fixSpan` - single- or double-ended fixed data span, or null
  `subrange` - subrange, if null 0-1 is assumed
  `isLog` - true for logarithmic scale, false for linear
Returns:
  definite range for plotting

### getMissingScales

public static Set<AuxScale> getMissingScales(PlotLayer[] layers, Map<AuxScale,Span> dataSpans, Map<AuxScale,Span> fixSpans)
Returns a list of scale objects for which calculations are required. A list of scale objects for which ranges are required is supplied, along with optional associated data and fixed value ranges. A list of those scales for which data scans are necessary, on the assumption that they are to be fed to the `calculateAuxSpans` method, is returned.

Parameters:
  `layers` - layers to be plotted
  `dataSpans` - ranges acquired by scanning data keyed by scale, (optional per scale)
  `fixSpans` - single- or double-ended fixed data ranges, keyed by scale (optional per scale)
Returns:
  list of scales for which data scans are required