Package org.eclipse.dawnsci.plotting.api

Interface IPlottingSystem<T>

All Superinterfaces:
org.eclipse.core.runtime.IAdaptable, IAnnotationSystem, IAxisSystem, IPrintablePlotting, IRegionSystem, ITraceSystem
All Known Implementing Classes:
AbstractPlottingSystem, PlottingSystemImpl, ThreadSafePlottingSystem
public interface IPlottingSystem<T> extends org.eclipse.core.runtime.IAdaptable, ITraceSystem, IRegionSystem, IAxisSystem, IAnnotationSystem, IPrintablePlotting
Represents a bridge to the plotting system. To get your plotting system use the class PlottingFactory. This will return the user preferred plotting. To use the plotting system follow this design (similar to RCP parts in 3.x): 

 IPlottingSystem system = PlottingFactory.createPlottingSystem(); // reads user preference if there are alternatives.
 
 In UI code
 system.createPlotPart(...); // Note that the title here is the key used to retrieve the plotter in future.
 
 Create some 1D plots in one go
 system.createPlot1D(...); // Does not have to be in the UI thread.
 
 Configure a plot in detail, does have to be in UI thread
 ILineTrace trace = system.createLineTrace(...);
 trace.setTraceColor(...)
 trace.setLineWidth(...)
 trace.setXXX(...)
 
 system.addTrace(trace);
 
 This is true for any trace, the paradigm is 'create, modify, add' in the trace lifecycle.
 
 
 The plotting system uses listeners extensively to notify of the user doing things. It is likely that the
 events in future will increase as more features become available.
 
 At the end:
 system.dispose(); // This should be called to clean up UI. Do not forget to remove listeners in the 
                   // dispose as well.

  • Field Details

  • Method Details

    • getTitle

      String getTitle()
      Get the current title being used for the plot.
      Returns:

    • setTitle

      void setTitle(String title)
      Call to set the plot title. NOTE The title may be used for keys used to determine if traces are unique and should be set to a meaningful string, i.e. not "Plot".
      Parameters:
      title -

    • setTitleColor

      void setTitleColor(org.eclipse.swt.graphics.Color color)
      Call to set the plot title color.
      Parameters:
      title -

    • setBackgroundColor

      void setBackgroundColor(org.eclipse.swt.graphics.Color color)
      Set the back ground color of the plot.
      Parameters:
      title -

    • createPlotPart

      void createPlotPart(T parent, String plotName, org.eclipse.ui.IActionBars bars, PlotType hint, org.eclipse.ui.IWorkbenchPart part)
      Call to create the UI component dealing with the plotting.
      Parameters:
      parent -
      plotName -
      bars - - may be null
      hint -
      part - - may be null

    • getPlotName

      String getPlotName()
      The plot name corresponding to the name used in the PlottingFactory. For file plots in editors this will be the file name and for views such as 'Plot 1' etc it will be the view name (Plot 1).
      Returns:

    • createPlot1D

      List<ITrace> createPlot1D(org.eclipse.january.dataset.IDataset x, List<? extends org.eclipse.january.dataset.IDataset> ys, org.eclipse.core.runtime.IProgressMonitor monitor)
      This method is Thread safe - so no need to call from UI thread! See also ITraceSystem for flexible trace manipulation. For 1D - x is the x axis, ys is the y traces. X may be null when plotting with indices. This call will also plot in 3D if the plotting mode is setting to PlotType.XY_STACKED_3D first. A 3D plot will be produced staggering the 1D data in Z. NOTE: The call createPlot1D(y, null, monitor) is no longer allowed. It should be: createPlot1D(null, Arrays.asList(y), monitor). NOTE: Using this option plots everything on the current x and y axes. These are the default axes, to change axes, use createAxis(...) then setActiveAxis(...). Then subsequent plotting will plot to these active axes. Does not have to be called in the UI thread - any thread will do. Should be called to switch the entire plot contents. There is append for 1D plotting used for single points. @see IPlottingSystem.append(...) Each call to createPlot1D(...) adds to the plot and the current selected axes, use reset() to clear the plot. If a IDataset passed into the ys array is an instance of IErrorDataset and the getError() is non-null, error bars will be switched on automatically.
      Parameters:
      x - - may be null
      ys - - may not be null or empty
      monitor -
      mode -
      Returns:
      List of ITrace objects plotted, may be null. Normally you can cast these to ILineTrace as all 1D plotting systems will wholly or partially support ILineTrace. If plotting mode is XY_STACKED_3D then will return a list of size 1 with the trace of type IStackTrace.

    • createPlot1D

      List<ITrace> createPlot1D(org.eclipse.january.dataset.IDataset x, List<? extends org.eclipse.january.dataset.IDataset> ys, String title, org.eclipse.core.runtime.IProgressMonitor monitor)
      Parameters:
      x -
      ys -
      title - - specifies the title instead of creating one.
      monitor -
      Returns:
      See Also:

    • createPlot1D

      List<ITrace> createPlot1D(org.eclipse.january.dataset.IDataset x, List<? extends org.eclipse.january.dataset.IDataset> ys, List<String> dataNames, String title, org.eclipse.core.runtime.IProgressMonitor monitor)
      Parameters:
      x -
      ys -
      dataNames - - If the data plotted has names which will be used in Filters these can be set here.
      title - - specifies the title instead of creating one.
      monitor -
      Returns:
      See Also:

    • updatePlot1D

      List<ITrace> updatePlot1D(org.eclipse.january.dataset.IDataset x, List<? extends org.eclipse.january.dataset.IDataset> ys, org.eclipse.core.runtime.IProgressMonitor monitor)
      This method is Thread safe - so no need to call from UI thread! Attempts to update any ILineTraces with the same name as the ys pass in, otherwise will call createPlot1D(...) NOTE This will not update the title at the moment if the traces exist. If a IDataset passed into the ys array is an instance of IErrorDataset and the getError() is non-null, error bars will be switched on automatically [UNLESS the trace exists and setErrorBarEnabled(false) has been called on the ILineTrace already].
      Parameters:
      x - - may be null, if null indices of y are used
      ys - - must not be null
      monitor -
      Returns:

    • updatePlot1D

      List<ITrace> updatePlot1D(org.eclipse.january.dataset.IDataset x, List<? extends org.eclipse.january.dataset.IDataset> ys, List<String> dataNames, org.eclipse.core.runtime.IProgressMonitor monitor)
      Parameters:
      x - - may be null, if null indices of y are used
      ys - - must not be null
      dataNames - - If the data plotted has names which will be used in Filters these can be set here.
      monitor -
      Returns:

    • updatePlot1D

      List<ITrace> updatePlot1D(org.eclipse.january.dataset.IDataset x, List<? extends org.eclipse.january.dataset.IDataset> ys, String plotTitle, org.eclipse.core.runtime.IProgressMonitor monitor)
      Parameters:
      x - - may be null, if null indices of y are used
      ys - - must not be null
      plotTitle - - The name to use as the title of the plot, providing something new is plotted, otherwise leaves title unchanged.
      monitor -
      Returns:

    • createPlot2D

      ITrace createPlot2D(org.eclipse.january.dataset.IDataset image, List<? extends org.eclipse.january.dataset.IDataset> axes, org.eclipse.core.runtime.IProgressMonitor monitor)
      This method is Thread safe - so no need to call from UI thread! See also ITraceSystem for flexible trace manipulation. For 2D - x is the image dataset, ys is the axes. It will also plot in 3D if the plotting mode is setting to PlotType.SURFACE first. Does not have to be called in the UI thread. Should be called to switch the entire plot contents.
      Parameters:
      image -
      axes - - may be null for pixels only. They must be data sets of the same size as the image. The first dataset is the x-axis in standard orientation, the second is the y-axis.
      monitor -
      mode -
      Returns:
      Image trace plotted. You can normally cast this trace to an IImageTrace for PlotType.IMAGE and and ISurfaceTrace for PlotType.SURFACE. You can use any image methods offered by these interface.

    • createPlot2D

      ITrace createPlot2D(org.eclipse.january.dataset.IDataset image, List<? extends org.eclipse.january.dataset.IDataset> axes, String dataName, org.eclipse.core.runtime.IProgressMonitor monitor)
      Parameters:
      image -
      axes -
      dataName - - If the data plotted has a name which will be used in Filters this can be set here.
      monitor -
      Returns:

    • updatePlot2D

      ITrace updatePlot2D(org.eclipse.january.dataset.IDataset image, List<? extends org.eclipse.january.dataset.IDataset> axes, org.eclipse.core.runtime.IProgressMonitor monitor)
      This method is Thread safe - so no need to call from UI thread! This method is similar to createPlot2D(...) however calling this method swaps the image data for a plot - keeping zoom level intact. It can be used for a live update of an image plot for instance. If there is no image to update, createPlot2D(...) will be called instead automatically.
      Parameters:
      image -
      axes -
      monitor -
      Returns:

    • updatePlot2D

      ITrace updatePlot2D(org.eclipse.january.dataset.IDataset image, List<? extends org.eclipse.january.dataset.IDataset> axes, String dataName, org.eclipse.core.runtime.IProgressMonitor monitor)
      Parameters:
      image -
      axes -
      dataName - - If the data plotted has a name which will be used in Filters this can be set here.
      monitor -
      Returns:

    • setPlotType

      void setPlotType(PlotType plotType)
      Set the plot type. For instance if requiring a 3D surface plot of an image Call setPlotType(PlotType.SURFACE) followed by createPlot2D(...) Do not call before createPlotPart(...) THREAD SAFE
      Parameters:
      plotType -

    • append

      void append(String dataSetName, Number xValue, Number yValue, org.eclipse.core.runtime.IProgressMonitor monitor) throws Exception
      This method can be used to add a single plot data point to an individual 1D plot already created in createPlot(...). The dataSetName argument is the same as the name of the original data set plotted, the data is added to this plot efficiently. Example of starting a plot with nothing and then adding points: final Dataset y = DatasetFactory.zero(DoubleDataset.class); y.setName("y") plottingSystem.createPlot(y, null, PlotType.PT1D, mon); ...Update, x value indices in this case plottingSystem.append("y", y.getSize()+1, 10, mon); Call this update method in any thread, it will do the update in the UI thread if not already called in the UI thread.
      Parameters:
      dataSetName -
      xValue - - may be null if using indices
      yValue -
      monitor - - often null, this will be a fast operation.
      Throws:
      Exception

    • reset

      void reset()
      Call to tell the plot to plot nothing and reset axes. Thread safe.

    • resetAxes

      void resetAxes()
      Call to tell the plot to reset axes. Thread safe.
      Specified by:
      resetAxes in interface IAxisSystem

    • clear

      void clear()
      Call to tell the plot to remove data and leave axes unchanged. Thread safe.

    • dispose

      void dispose()
      Call to mark widgets and plotting as no longer required. This will be called when the part is disposed.

    • repaint

      void repaint()
      Redraws all the data. Calls repaint(isRescale()) Thread safe.

    • repaint

      void repaint(boolean autoScale)
      Repaint with rescale of autoScale is true. Thread safe.
      Parameters:
      autoScale -

    • getPlotComposite

      T getPlotComposite()
      The plot composite which plots are being drawn on. Use this method with caution
      Returns:

    • getSelectionProvider

      org.eclipse.jface.viewers.ISelectionProvider getSelectionProvider()
      This ISelectionProvider will provide StructuredSelections which have been made in the graph. It may be registered as a selection provider for the part using this IPlottingSystem. The StructuredSelection will contain objects such as 'LinerROI' for the selection inside the graph.
      Returns:

    • getPlotType

      PlotType getPlotType()
      Will return the current plot type 1D, 2D etc.

    • is2D

      boolean is2D()
      Returns:
      true if some or all of the plotted data is 2D or images.

    • getActionBars

      org.eclipse.ui.IActionBars getActionBars()
      Returns:
      the action bars containing the graph actions.

    • getPlotActionSystem

      IPlotActionSystem getPlotActionSystem()
      Gives access to the action manager for removing and filling different actions.
      Returns:

    • setDefaultCursor

      void setDefaultCursor(int cursorType)
      The cursor type used normally when no zoom or other cursor is active. NORMAL is the arrow, CROSS is a cross

    • setKeepAspect

      void setKeepAspect(boolean b)
      Set the plotting System aspect ratio on/off
      Parameters:
      b -

    • setEnabled

      void setEnabled(boolean enabled)
      Can be used to grey out plotting component during updates. Thread safe, can be called from any thread.
      Parameters:
      enabled -

    • isEnabled

      boolean isEnabled()
      returns if the plotting system is
      Returns:

    • isShowIntensity

      boolean isShowIntensity()
      Returns:
      true if intensity is shown for images.

    • setShowIntensity

      void setShowIntensity(boolean b)
      Shows or not the intensity scale The intensity scale is displayed (set to True) every time there is an image update If you want to hide it (set to False), make sure this method is called after each update.
      Parameters:
      b -

    • isShowValueLabels

      boolean isShowValueLabels()
      Returns:
      true if values will be shown when the user zooms in far enough

    • setShowValueLabels

      void setShowValueLabels(boolean b)
      Shows or not the values on high zoom
      Parameters:
      b -

    • setShowLegend

      void setShowLegend(boolean b)
      Sets the legends setting on/off
      Parameters:
      b -

    • isDisposed

      boolean isDisposed()
      Returns whether the IPlottingSystem is disposed
      Returns:

    • setColorOption

      void setColorOption(ColorOption colorOption)
      Sets the Color option
      Parameters:
      colorOption -

    • setColorScheme

      void setColorScheme(String colorScheme)
      Sets the color scheme
      Parameters:
      colorScheme -

    • getColorScheme

      String getColorScheme()
      Returns:
      color scheme (can be null for default from preference)

    • isRescale

      boolean isRescale()
      Returns whether the plot should rescale when replotted.
      Returns:
      rescale

    • setRescale

      void setRescale(boolean rescale)
      Sets whether the the plot should rescale when replotted
      Parameters:
      rescale -

    • setFocus

      void setFocus()
      May be called to ensure the widget doing the plotting has focus.

    • getPart

      org.eclipse.ui.IWorkbenchPart getPart()
      The underlying IWorkbenchPart, if any
      Returns:
      IWorkbenchPart, may be null

    • setControl

      org.eclipse.swt.widgets.Control setControl(org.eclipse.swt.widgets.Control alternative, boolean showPlotToolbar)
      Expert use only: This method replaces the plotting system control, for instance the light weight plot viewer with an alternative widget. It returns the widget that was replaced in the plotting system. For instance the light weight canvas if in light weight mode. This can then be called using setControl(original) when the alternative UI for editing the plot is finished with. An example of doing this is replacing the plot with a custom slicing part like the Hyper3D slicing tool.
      Parameters:
      alternative -
      Returns:

    • getLineTracePreferences

      LineTracePreferences getLineTracePreferences()
      Returns:
      preferences for line traces

    • restorePreferences

      void restorePreferences(org.eclipse.ui.IMemento memento)
      Restore some preferences from given memento
      Parameters:
      memento -

    • savePreferences

      void savePreferences(org.eclipse.ui.IMemento memento)
      Save some preferences in given memento
      Parameters:
      memento -

    • getActiveViewer

      default IPlottingSystemViewer<T> getActiveViewer()