Class AbstractPlot2Task

java.lang.Object
uk.ac.starlink.ttools.plot2.task.AbstractPlot2Task
All Implemented Interfaces:
uk.ac.starlink.task.Task, DynamicTask
Direct Known Subclasses:
GenericPlot2Task, TypedPlot2Task

public abstract class AbstractPlot2Task extends Object implements uk.ac.starlink.task.Task, DynamicTask
Abstract superclass for tasks performing plot2 plots using STILTS. Concrete subclasses must supply the PlotType (perhaps from the environment), and may customise the visible task parameter set.

As currently implemented, this will only work with single-zone plots or multi-zone plots with per-zone trimmings and shade axes. Multi-zone plots with global trimming or shade axes must be handled using custom code.

Since:
22 Aug 2014
Author:
Mark Taylor
  • Field Details

  • Constructor Details

    • AbstractPlot2Task

      protected AbstractPlot2Task(boolean allowAnimate, boolean hasZoneSuffixes)
      Constructor with explicit animation capability.
      Parameters:
      allowAnimate - true iff animation options should be provided
      hasZoneSuffixes - true iff zone content can be controlled explicitly by use of parameter suffixes
  • Method Details

    • getPlotContext

      public abstract PlotContext<?,?> getPlotContext(uk.ac.starlink.task.Environment env) throws uk.ac.starlink.task.TaskException
      Concrete subclasses must implement this method to provide the PlotType and other information from the environment that may not be available at construction time.
      Parameters:
      env - execution environment
      Returns:
      context
      Throws:
      uk.ac.starlink.task.TaskException
    • getConfigParamDefault

      protected abstract <T> String getConfigParamDefault(uk.ac.starlink.task.Environment env, ConfigKey<T> key, String[] suffixes) throws uk.ac.starlink.task.TaskException
      May provide a default value for a given config parameter that is sensitive to the content of the execution environment. This is here to provide a hook for subclasses to set up defaults for some config parameters on the basis of what layers are present.
      Parameters:
      env - execution environment
      key - config key for which a parameter is required
      suffixes - ordered list of the plot layer suffixes in use for the plot being performed
      Returns:
      default for parameter getting value for key, or null if none is obvious
      Throws:
      uk.ac.starlink.task.TaskException
    • getBasicParameters

      public final uk.ac.starlink.task.Parameter<?>[] getBasicParameters()
      Returns the list of parameters supplied by the AbstractPlot2Task implementation. Subclasses should include these alongside any they want to add for presentation to the user.
      Returns:
      basic parameter list
    • createExecutable

      public uk.ac.starlink.task.Executable createExecutable(uk.ac.starlink.task.Environment env) throws uk.ac.starlink.task.TaskException
      Specified by:
      createExecutable in interface uk.ac.starlink.task.Task
      Throws:
      uk.ac.starlink.task.TaskException
    • hasZoneSuffixes

      public boolean hasZoneSuffixes()
      Indicates whether relevant parameters can be suffixed by zone label for explicit control of per-zone characteristics.
      Returns:
      true iff zone suffixes are in use
    • getXpixParameter

      public uk.ac.starlink.task.IntegerParameter getXpixParameter()
      Returns the parameter for assigning the external horizontal extent of the plot.
      Returns:
      xpix parameter
    • getYpixParameter

      public uk.ac.starlink.task.IntegerParameter getYpixParameter()
      Returns the parameter for assigning the external vertical extent of the plot.
      Returns:
      ypix parameter
    • getSequenceParameter

      public uk.ac.starlink.task.Parameter<String[]> getSequenceParameter()
      Returns the parameter for determining the sequence of layers appearing in the plot.
      Returns:
      sequence parameter
    • getLegendParameter

      public uk.ac.starlink.task.Parameter<Boolean> getLegendParameter()
      Returns the parameter for indicating whether the legend will be visible.
      Returns:
      legend visible parameter
    • getLegendBorderParameter

      public uk.ac.starlink.task.Parameter<Boolean> getLegendBorderParameter()
      Returns the parameter for indicating whether the legend border will be visible.
      Returns:
      legend border parameter
    • getLegendOpaqueParameter

      public uk.ac.starlink.task.Parameter<Boolean> getLegendOpaqueParameter()
      Returns the parameter for indicating whether the legend background will be opaque.
      Returns:
      legend opaque parameter
    • getLegendSequenceParameter

      public uk.ac.starlink.task.Parameter<String[]> getLegendSequenceParameter()
      Returns the parameter for determining the sequence and inclusion of layers in the legend.
      Returns:
      legend sequence parameter
    • getPaddingParameter

      public uk.ac.starlink.task.Parameter<Padding> getPaddingParameter()
      Returns the parameter for assigning the plot external padding.
      Returns:
      padding parameter
    • getDataStoreParameter

      public uk.ac.starlink.task.Parameter<DataStoreFactory> getDataStoreParameter()
      Returns the parameter for configurig the data storage.
      Returns:
      data storage parameter
    • getBitmapParameter

      public uk.ac.starlink.task.BooleanParameter getBitmapParameter()
      Returns the parameter used to force bitmap output.
      Returns:
      force bitmap parameter
    • getCompositorParameter

      public uk.ac.starlink.task.Parameter<Compositor> getCompositorParameter()
      Returns the parameter for configuring the compositor.
      Returns:
      compositor parameter
    • createCustomConfigMap

      public ConfigMap createCustomConfigMap(uk.ac.starlink.task.Environment env) throws uk.ac.starlink.task.TaskException
      Provides any additional config keys (beyond layer style and aux map) that should be provided for layer creation. The default implementation returns an empty map, but this behaviour may be overridden by subclasses.
      Parameters:
      env - execution environment
      Returns:
      custom config entries
      Throws:
      uk.ac.starlink.task.TaskException
    • createPlotIcon

      public Icon createPlotIcon(uk.ac.starlink.task.Environment env) throws uk.ac.starlink.task.TaskException, IOException, InterruptedException
      Returns an Icon that paints the plot described by a value-bearing execution environment. This utility method is not used for executing this class.
      Parameters:
      env - execution environment
      Returns:
      plot icon
      Throws:
      uk.ac.starlink.task.TaskException
      IOException
      InterruptedException
    • testEnv

      public void testEnv(uk.ac.starlink.task.Environment env) throws uk.ac.starlink.task.TaskException
      Prepares a plot for this task as specified by a given environment, but does not run any of the actual plotting code. If this utility method completes without error, there is a good chance that the specified plot will also run without error.
      Parameters:
      env - populated environment
      Throws:
      uk.ac.starlink.task.TaskException - in case of error
    • createPlotComponent

      public PlotDisplay<?,?> createPlotComponent(uk.ac.starlink.task.Environment env, boolean caching) throws uk.ac.starlink.task.TaskException, IOException, InterruptedException
      Returns a graphical component that displays an interactive view of the plot described by a value-bearing execution environment. This utility method is not used for executing the task defined by this class.
      Parameters:
      env - execution environment
      caching - whether data and plot should be cached or re-read at every repaint
      Returns:
      active plot view component
      Throws:
      uk.ac.starlink.task.TaskException
      IOException
      InterruptedException
    • getContextParameters

      public uk.ac.starlink.task.Parameter<?>[] getContextParameters(uk.ac.starlink.task.Environment env) throws uk.ac.starlink.task.TaskException
      Description copied from interface: DynamicTask
      Returns the parameters for this task in the context of a given execution environment. If the environment is empty, this should give the same result as Task.getParameters(), but found settings of parameters in the presented environment may lead to parameters being added to or removed from the list.

      This ought not to result in additional prompts to the user.

      Specified by:
      getContextParameters in interface DynamicTask
      Parameters:
      env - execution environment
      Returns:
      list of known parameters
      Throws:
      uk.ac.starlink.task.TaskException
    • getParameterByName

      public uk.ac.starlink.task.Parameter<?> getParameterByName(uk.ac.starlink.task.Environment env, String paramName) throws uk.ac.starlink.task.TaskException
      Description copied from interface: DynamicTask
      Attempts to find a parameter with a given name that might be used by this task in the content of the given environment.

      This ought not to result in additional prompts to the user.

      Specified by:
      getParameterByName in interface DynamicTask
      Parameters:
      env - execution environment
      paramName - requested parameter name
      Returns:
      parameter with the given name, or null
      Throws:
      uk.ac.starlink.task.TaskException
    • createPlotConfiguration

      protected <P, A> PlotConfiguration<P,A> createPlotConfiguration(uk.ac.starlink.task.Environment env, PlotContext<P,A> context) throws uk.ac.starlink.task.TaskException
      Turns an execution environment (containing value-bearing parameters) into an object with all the required plot configuration information.
      Parameters:
      env - execution environment
      context - plot context
      Returns:
      plot configuration
      Throws:
      uk.ac.starlink.task.TaskException
    • createLegend

      public Icon createLegend(uk.ac.starlink.task.Environment env, Map<String,PlotLayer> layerMap, String[] suffixSeq) throws uk.ac.starlink.task.TaskException
      Turns the map of defined layers into a legend icon.
      Parameters:
      env - execution environment
      layerMap - suffix->layer map for all defined layers
      suffixSeq - ordered array of suffixes for layers to be plotted
      Returns:
      legend icon, may be null
      Throws:
      uk.ac.starlink.task.TaskException
    • getPlotters

      public static Map<String,Plotter<?>> getPlotters(uk.ac.starlink.task.Environment env, PlotContext<?,?> context) throws uk.ac.starlink.task.TaskException
      Returns a map of suffix strings to Plotter objects. Each suffix string is appended to parameters associated with the relevant plotter as a namespacing device on the command line.
      Parameters:
      env - execution environment
      context - plot context
      Returns:
      mapping from suffixes to plotters for the environment
      Throws:
      uk.ac.starlink.task.TaskException
    • getCaptioner

      public Captioner getCaptioner(uk.ac.starlink.task.Environment env) throws uk.ac.starlink.task.TaskException
      Acquires a captioner from the environment. At present, a single captioner is used for labelling the legend and any axes; this is also the one that will be used by default for any label-type plot layers. However you could refine it to use different parameter sets for different purposes.
      Parameters:
      env - execution environment
      Returns:
      captioner
      Throws:
      uk.ac.starlink.task.TaskException
    • createShadeAxisFactory

      public ShadeAxisFactory createShadeAxisFactory(uk.ac.starlink.task.Environment env, PlotLayer[] layers, String zoneSuffix) throws uk.ac.starlink.task.TaskException
      Acquires a ShadeAxisFactory from the environment for a given plot zone.
      Parameters:
      env - execution environment
      layers - layers that will be plotted
      zoneSuffix - identifier for zone whose shader is to be calculated
      Returns:
      shade axis factory, may be null
      Throws:
      uk.ac.starlink.task.TaskException
    • createBasicConfigMap

      public static ConfigMap createBasicConfigMap(uk.ac.starlink.task.Environment env, ConfigKey<?>[] keys) throws uk.ac.starlink.task.TaskException
      Returns a config map based on given keys with values derived from the execution environment. There is no funny business with appending suffixes etc.
      Parameters:
      env - execution environment
      keys - config keys
      Returns:
      config map
      Throws:
      uk.ac.starlink.task.TaskException
    • getCoordValue

      public static CoordValue getCoordValue(uk.ac.starlink.task.Environment env, Coord coord, String suffix) throws uk.ac.starlink.task.TaskException
      Turns a coord into a CoordValue.
      Parameters:
      env - execution environment
      coord - coordinate definition
      suffix - suffix to append to parameter name
      Returns:
      coordinate with expression values acquired from environment
      Throws:
      uk.ac.starlink.task.TaskException
    • createLayerSuffixedConfigMap

      public static ConfigMap createLayerSuffixedConfigMap(uk.ac.starlink.task.Environment env, ConfigKey<?>[] configKeys, String layerSuffix) throws uk.ac.starlink.task.TaskException
      Returns a ConfigMap specific to a given layer derived from the assignments made in a given execution environment, based on config keys and a layer identifier.
      Parameters:
      env - execution environment bearing the parameter values
      configKeys - layer-specific configuration keys to find values for
      layerSuffix - layer identifier string appended to config key shortnames to make env parameter names
      Returns:
      config map with values for the supplied keys
      Throws:
      uk.ac.starlink.task.TaskException
    • createConfigMap

      public static ConfigMap createConfigMap(uk.ac.starlink.task.Environment env, ConfigKey<?>[] configKeys, ConfigParameterFactory cpFact) throws uk.ac.starlink.task.TaskException
      Returns a ConfigMap derived from the assignments made in a given execution environment.
      Parameters:
      env - execution environment bearing the parameter values
      configKeys - configuration keys to find values for
      cpFact - turns config keys into Parameters
      Returns:
      config map with values for the supplied keys
      Throws:
      uk.ac.starlink.task.TaskException
    • getInputTable

      public static uk.ac.starlink.table.StarTable getInputTable(uk.ac.starlink.task.Environment env, String suffix) throws uk.ac.starlink.task.TaskException
      Returns a table from the environment.
      Parameters:
      env - execution environment
      suffix - parameter suffix
      Returns:
      table
      Throws:
      uk.ac.starlink.task.TaskException
    • createTableParameter

      public static InputTableParameter createTableParameter(String suffix)
      Returns a parameter for acquiring a data table.
      Parameters:
      suffix - layer-specific suffix
      Returns:
      table parameter
    • createFilterParameter

      public static FilterParameter createFilterParameter(String suffix, InputTableParameter tableParam)
      Returns a parameter for acquiring a filter applied to the table input for a given layer.
      Parameters:
      suffix - layer-specific suffix
      tableParam - input table parameter associated with the layer
      Returns:
      filter parameter
    • createLabelParameter

      public static uk.ac.starlink.task.Parameter<String> createLabelParameter(String suffix)
      Returns a parameter to get a textual label corresponding to the layer identified by a given layer suffix. This label is displayed in the legend.
      Parameters:
      suffix - layer suffix
      Returns:
      parameter to get legend label for layer
    • createTitleParameter

      public uk.ac.starlink.task.Parameter<String> createTitleParameter(String suffix)
      Returns a parameter to get a plot title for the zone identified by a given zone suffix.
      Parameters:
      suffix - zone suffix, or either null or empty string for all zones
      Returns:
      parameter to get plot title for zone
    • createAuxLabelParameter

      public uk.ac.starlink.task.StringParameter createAuxLabelParameter(String suffix)
      Returns a parameter for acquiring the aux ramp label.
      Parameters:
      suffix - zone suffix
      Returns:
      parameter
    • createAuxVisibleParameter

      public uk.ac.starlink.task.BooleanParameter createAuxVisibleParameter(String suffix)
      Returns a parameter for determining whether the aux colour ramp is painted for a given plot zone.
      Parameters:
      suffix - zone suffix
      Returns:
      parameter
    • createAuxCrowdParameter

      public uk.ac.starlink.task.DoubleParameter createAuxCrowdParameter(String suffix)
      Returns a parameter for determining crowding on the aux axis.
      Parameters:
      suffix - zone suffix
      Returns:
      parameter
    • createAuxWidthParameter

      public uk.ac.starlink.task.IntegerParameter createAuxWidthParameter(String suffix)
      Returns a parameter for determining aux colour ramp lateral size in pixels.
      Parameters:
      suffix - zone suffix
      Returns:
      parameter
    • createLegendPositionParameter

      public DoubleArrayParameter createLegendPositionParameter(String suffix)
      Returns a parameter to get the legend position for the zone identified by a given zone suffix.
      Parameters:
      suffix - zone suffix, or either null or empty string for all zones
      Returns:
      parameter to get legend position for zone
    • hasDomainMappers

      public static boolean hasDomainMappers(Input input)
      Indicates whether a DomainMapper should be sought for a given Input.
      Parameters:
      input - input specifier
      Returns:
      true iff input's Domain supports multiple known mappers
    • createLayerTypeParameter

      public static LayerTypeParameter createLayerTypeParameter(String suffix, PlotContext<?,?> context)
      Returns a parameter for acquiring a plotter.
      Parameters:
      suffix - parameter name suffix
      context - plot context
      Returns:
      plotter parameter
    • createZoneParameter

      public static uk.ac.starlink.task.Parameter<String> createZoneParameter(String layerSuffix)
      Returns a parameter for associating a zone identifier with a given layer. The value acquired by this parameter is the zone suffix.
      Parameters:
      layerSuffix - identifier for the layer whose zone is to be determined
      Returns:
      zone suffix parameter
    • createDataParameter

      public static uk.ac.starlink.task.StringParameter createDataParameter(Input input, String suffix, boolean fullDetail)
      Returns a parameter for acquiring a column of data.
      Parameters:
      input - specifies input value required from user
      suffix - layer-specific suffix
      fullDetail - if true, extra detail is appended to the description
      Returns:
      data parameter
    • createDomainMapperParameter

      public static uk.ac.starlink.task.Parameter<uk.ac.starlink.table.DomainMapper> createDomainMapperParameter(Input input, String suffix)
      Returns a parameter for specifying the DomainMapper associated with a given Input.
      Parameters:
      input - coordinate specifier
      suffix - layer suffix
      Returns:
      domain mapper selection parameter
    • createPaintModeParameter

      public static PaintModeParameter createPaintModeParameter()
      Returns a parameter for specifying a paint mode.
      Returns:
      paint mode parameter
    • createPlotIcon

      public static <P, A> Icon createPlotIcon(Ganger<P,A> ganger, SurfaceFactory<P,A> surfFact, ZoneContent<P,A>[] contents, Trimming[] trimmings, ShadeAxisKit[] shadeKits, PaperTypeSelector ptSel, Compositor compositor, DataStore dataStore, int xpix, int ypix, boolean forceBitmap)
      Creates an icon which will paint the content of a plot. This icon is expected to be painted once and then discarded, so it's not cached.

      The contents array must have a number of entries that matches the zone count of the ganger. The trimmings and shadeKits are supplied as arrays, and in each case may be either a 1- or nzone-element array depending on the Ganger's Ganger.isTrimmingGlobal()/Ganger.isShadingGlobal() flags.

      Parameters:
      ganger - defines plot surface grouping
      surfFact - surface factory
      contents - zone contents (nz-element array)
      trimmings - zone trimmings (nz- or 1-element array, elements may be null)
      shadeKits - shader axis kits by zone (nz- or 1-element array, elements may be null)
      ptSel - paper type selector
      compositor - compositor for pixel composition
      dataStore - data storage object
      xpix - horizontal size of icon in pixels
      ypix - vertical size of icon in pixels
      forceBitmap - true to force bitmap output of vector graphics, false to use default behaviour
      Returns:
      icon icon for plotting
    • getZoneKeyParams

      public final List<uk.ac.starlink.task.Parameter<?>> getZoneKeyParams(ConfigKey<?>[] keys)
      Returns a list of parameters suffixed by zone based on a list of ConfigKeys.
      Parameters:
      keys - config keys
      Returns:
      parameters for acquiring config key values