Class AbstractPlot2Task

  • All Implemented Interfaces:
    uk.ac.starlink.task.Task, DynamicTask
    Direct Known Subclasses:
    GenericPlot2Task, TypedPlot2Task

    public abstract class AbstractPlot2Task
    extends java.lang.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.
    Since:
    22 Aug 2014
    Author:
    Mark Taylor
    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected AbstractPlot2Task​(boolean allowAnimate, GangerFactory<?,​?> gangerFact)
      Constructor with explicit animation capability.
      protected AbstractPlot2Task​(GangerFactory<?,​?> gangerFact)
      Constructor with default animation capability.
    • Method Summary

      All Methods Static Methods Instance Methods Abstract Methods Concrete Methods 
      Modifier and Type Method Description
      uk.ac.starlink.task.DoubleParameter createAuxCrowdParameter​(java.lang.String suffix)
      Returns a parameter for determining crowding on the aux axis.
      uk.ac.starlink.task.StringParameter createAuxLabelParameter​(java.lang.String suffix)
      Returns a parameter for acquiring the aux ramp label.
      uk.ac.starlink.task.BooleanParameter createAuxVisibleParameter​(java.lang.String suffix)
      Returns a parameter for determining whether the aux colour ramp is painted for a given plot zone.
      uk.ac.starlink.task.IntegerParameter createAuxWidthParameter​(java.lang.String suffix)
      Returns a parameter for determining aux colour ramp lateral size in pixels.
      ConfigMap createCustomConfigMap​(uk.ac.starlink.task.Environment env)
      Provides any additional config keys (beyond layer style and aux map) that should be provided for layer creation.
      static uk.ac.starlink.task.StringParameter createDataParameter​(Input input, java.lang.String suffix, boolean fullDetail)
      Returns a parameter for acquiring a column of data.
      static uk.ac.starlink.task.Parameter<uk.ac.starlink.table.DomainMapper> createDomainMapperParameter​(Input input, java.lang.String suffix)
      Returns a parameter for specifying the DomainMapper associated with a given Input.
      uk.ac.starlink.task.Executable createExecutable​(uk.ac.starlink.task.Environment env)  
      static FilterParameter createFilterParameter​(java.lang.String suffix, InputTableParameter tableParam)
      Returns a parameter for acquiring a filter applied to the table input for a given layer.
      static uk.ac.starlink.task.Parameter<java.lang.String> createLabelParameter​(java.lang.String suffix)
      Returns a parameter to get a textual label corresponding to the layer identified by a given layer suffix.
      static LayerTypeParameter createLayerTypeParameter​(java.lang.String suffix, PlotContext<?,​?> context)
      Returns a parameter for acquiring a plotter.
      DoubleArrayParameter createLegendPositionParameter​(java.lang.String suffix)
      Returns a parameter to get the legend position for the zone identified by a given zone suffix.
      static PaintModeParameter createPaintModeParameter()
      Returns a parameter for specifying a paint mode.
      PlotDisplay<?,​?> createPlotComponent​(uk.ac.starlink.task.Environment env, boolean caching)
      Returns a graphical component that displays an interactive view of the plot described by a value-bearing execution environment.
      javax.swing.Icon createPlotIcon​(uk.ac.starlink.task.Environment env)
      Returns an Icon that paints the plot described by a value-bearing execution environment.
      static <P,​A>
      javax.swing.Icon
      createPlotIcon​(Ganger<P,​A> ganger, SurfaceFactory<P,​A> surfFact, int nz, ZoneContent[] contents, P[] profiles, A[] aspects, ShadeAxisFactory[] shadeFacts, Span[] shadeFixSpans, PaperTypeSelector ptSel, Compositor compositor, DataStore dataStore, int xpix, int ypix, boolean forceBitmap)
      Creates an icon which will paint the content of a plot.
      static InputTableParameter createTableParameter​(java.lang.String suffix)
      Returns a parameter for acquiring a data table.
      uk.ac.starlink.task.Parameter<java.lang.String> createTitleParameter​(java.lang.String suffix)
      Returns a parameter to get a plot title for the zone identified by a given zone suffix.
      static uk.ac.starlink.task.Parameter<java.lang.String> createZoneParameter​(java.lang.String layerSuffix)
      Returns a parameter for associating a zone identifier with a given layer.
      uk.ac.starlink.task.Parameter<?>[] getBasicParameters()
      Returns the list of parameters supplied by the AbstractPlot2Task implementation.
      protected abstract <T> java.lang.String getConfigParamDefault​(uk.ac.starlink.task.Environment env, ConfigKey<T> key, java.lang.String[] suffixes)
      May provide a default value for a given config parameter that is sensitive to the content of the execution environment.
      uk.ac.starlink.task.Parameter<?>[] getContextParameters​(uk.ac.starlink.task.Environment env)
      Returns the parameters for this task in the context of a given execution environment.
      uk.ac.starlink.task.Parameter<java.lang.Boolean> getLegendBorderParameter()
      Returns the parameter for indicating whether the legend border will be visible.
      uk.ac.starlink.task.Parameter<java.lang.Boolean> getLegendOpaqueParameter()
      Returns the parameter for indicating whether the legend background will be opaque.
      uk.ac.starlink.task.Parameter<java.lang.Boolean> getLegendParameter()
      Returns the parameter for indicating whether the legend will be visible.
      uk.ac.starlink.task.Parameter<java.lang.String[]> getLegendSequenceParameter()
      Returns the parameter for determining the sequence and inclusion of layers in the legend.
      uk.ac.starlink.task.Parameter<Padding> getPaddingParameter()
      Returns the parameter for assigning the plot external padding.
      uk.ac.starlink.task.Parameter<?> getParameterByName​(uk.ac.starlink.task.Environment env, java.lang.String paramName)
      Attempts to find a parameter with a given name that might be used by this task in the content of the given environment.
      abstract PlotContext<?,​?> getPlotContext​(uk.ac.starlink.task.Environment env)
      Concrete subclasses must implement this method to provide the PlotType and other information from the environment that may not be available at construction time.
      uk.ac.starlink.task.Parameter<java.lang.String[]> getSequenceParameter()
      Returns the parameter for determining the sequence of layers appearing in the plot.
      uk.ac.starlink.task.Parameter<java.lang.Integer> getXpixParameter()
      Returns the parameter for assigning the external horizontal extent of the plot.
      uk.ac.starlink.task.Parameter<java.lang.Integer> getYpixParameter()
      Returns the parameter for assigning the external vertical extent of the plot.
      java.util.List<uk.ac.starlink.task.Parameter<?>> getZoneKeyParams​(ConfigKey<?>[] keys)
      Returns a list of parameters suffixed by zone based on a list of ConfigKeys.
      static boolean hasDomainMappers​(Input input)
      Indicates whether a DomainMapper should be sought for a given Input.
      void testEnv​(uk.ac.starlink.task.Environment env)
      Prepares a plot for this task as specified by a given environment, but does not run any of the actual plotting code.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
      • Methods inherited from interface uk.ac.starlink.task.Task

        getParameters, getPurpose
    • Constructor Detail

      • AbstractPlot2Task

        protected AbstractPlot2Task​(boolean allowAnimate,
                                    GangerFactory<?,​?> gangerFact)
        Constructor with explicit animation capability.
        Parameters:
        allowAnimate - true iff animation options should be provided
        gangerFact - controls how plots can be grouped
      • AbstractPlot2Task

        protected AbstractPlot2Task​(GangerFactory<?,​?> gangerFact)
        Constructor with default animation capability.
        Parameters:
        gangerFact - controls how plots can be grouped
    • Method Detail

      • 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> java.lang.String getConfigParamDefault​(uk.ac.starlink.task.Environment env,
                                                                      ConfigKey<T> key,
                                                                      java.lang.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
      • getXpixParameter

        public uk.ac.starlink.task.Parameter<java.lang.Integer> getXpixParameter()
        Returns the parameter for assigning the external horizontal extent of the plot.
        Returns:
        xpix parameter
      • getYpixParameter

        public uk.ac.starlink.task.Parameter<java.lang.Integer> getYpixParameter()
        Returns the parameter for assigning the external vertical extent of the plot.
        Returns:
        ypix parameter
      • getSequenceParameter

        public uk.ac.starlink.task.Parameter<java.lang.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<java.lang.Boolean> getLegendParameter()
        Returns the parameter for indicating whether the legend will be visible.
        Returns:
        legend visible parameter
      • getLegendBorderParameter

        public uk.ac.starlink.task.Parameter<java.lang.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<java.lang.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<java.lang.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
      • 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 javax.swing.Icon createPlotIcon​(uk.ac.starlink.task.Environment env)
                                        throws uk.ac.starlink.task.TaskException,
                                               java.io.IOException,
                                               java.lang.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
        java.io.IOException
        java.lang.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,
                                                          java.io.IOException,
                                                          java.lang.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
        java.io.IOException
        java.lang.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,
                                                                   java.lang.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
      • createTableParameter

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

        public static FilterParameter createFilterParameter​(java.lang.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<java.lang.String> createLabelParameter​(java.lang.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<java.lang.String> createTitleParameter​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.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​(java.lang.String suffix)
        Returns a parameter for determining aux colour ramp lateral size in pixels.
        Parameters:
        suffix - zone suffix
        Returns:
        parameter
      • createLegendPositionParameter

        public DoubleArrayParameter createLegendPositionParameter​(java.lang.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​(java.lang.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<java.lang.String> createZoneParameter​(java.lang.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,
                                                                              java.lang.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,
                                                                                                                   java.lang.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> javax.swing.Icon createPlotIcon​(Ganger<P,​A> ganger,
                                                                  SurfaceFactory<P,​A> surfFact,
                                                                  int nz,
                                                                  ZoneContent[] contents,
                                                                  P[] profiles,
                                                                  A[] aspects,
                                                                  ShadeAxisFactory[] shadeFacts,
                                                                  Span[] shadeFixSpans,
                                                                  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.
        Parameters:
        ganger - defines plot surface grouping
        surfFact - surface factory
        nz - number of plot zones in gang
        contents - zone contents (nz-element array)
        aspects - plot surface aspects by zone (nz-element array)
        shadeFacts - shader axis factories by zone (nz-element array), elements may be null if not required
        shadeFixSpans - fixed shader ranges by zone (nz-element array) elements may be null for auto-range or if no shade axis
        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 java.util.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