# Class PlotScene<P,A>

java.lang.Object
uk.ac.starlink.ttools.plot2.PlotScene<P,A>

public class PlotScene<P,A> extends Object
Contains the state of a plot, which can be painted to a graphics context. The plot's aspect and dimensions can be changed, which means it can form the basis of a 'live' plot.

Since:
  5 Dec 2019
Author:
  Mark Taylor

## Constructor Summary

Constructors
Constructor
Description
`PlotScene(Ganger<P,A> ganger, SurfaceFactory<P,A> surfFact, ZoneContent<P,A>[] zoneContents, Trimming[] trimmings, ShadeAxisKit[] shadeKits, PaperTypeSelector ptSel, Compositor compositor, PlotCaching caching)`
Constructs a PlotScene containing multiple plot surfaces.
`PlotScene(SurfaceFactory<P,A> surfFact, ZoneContent<P,A> content, Trimming trimming, ShadeAxisKit shadeKit, PaperTypeSelector ptSel, Compositor compositor, Padding padding, PlotCaching caching)`
Constructs a PlotScene containing a single plot surface.

## Method Summary

Modifier and Type
Method
Description
`static Map<AuxScale,Span>`
`calculateNonShadeSpans(PlotLayer[] layers, Surface surface, Object[] plans, DataStore dataStore)`
Gathers requested ranging information from data, excluding the AuxScale.COLOR item (the aux shading axis).
`static Span`
`calculateShadeSpan(List<uk.ac.starlink.util.Bi<Surface, PlotLayer>> surfLayers, ShadeAxisKit shadeKit, Object[] plans, DataStore dataStore)`
Gathers ranging information for the aux shading axis from data.
`void`
`clearPlot()`
Clears the current cached plot image, if any, so that regeneration of the image from the data is forced when the next paint operation is performed; otherwise it may be copied from a cached image.
`static <P,A> PlotScene<P,A>`
`createGangScene(Ganger<P,A> ganger, SurfaceFactory<P,A> surfFact, PlotLayer[][] layerArrays, P[] profiles, ConfigMap[] aspectConfigs, Trimming[] trimmings, ShadeAxisKit[] shadeKits, PaperTypeSelector ptSel, Compositor compositor, DataStore dataStore, PlotCaching caching)`
Utility method to construct a ganged PlotDisplay, with aspect obtained from a supplied config map.
`IndicatedRow[]`
`findClosestRows(Surface surface, PlotLayer[] layers, Point point, DataStore dataStore)`
Assembles and returns a list of row indexes that are plotted close to a given graphics position.
`A[]`
`getAspects()`
Returns the most recently set aspects.
`Gang`
`getGang()`
Returns the current plot gang.
`Ganger<P,A>`
`getGanger()`
Returns the Ganger used by this scene.
`PlotLayer[]`
`getLayers(int iz)`
Returns the plot layers contained in a given zone.
`Surface[]`
`getSurfaces()`
Returns the current plot surfaces.
`int`
`getZoneIndex(Point pos)`
Returns the index of the zone in whose data bounds a given point lies.
`void`
`paintScene(Graphics g, Rectangle extBounds, DataStore dataStore)`
Paints the contents of this plot to a graphics context.
`void`
`prepareScene(Rectangle extBounds, DataStore dataStore)`
Ensures that the plot surfaces are ready to plot this scene.
`boolean`
`setAspects(A[] aspects)`
Sets the aspects of the plot zones.

### Methods inherited from class Object

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

## Constructor Details

### PlotScene

public PlotScene(Ganger<P,A> ganger, SurfaceFactory<P,A> surfFact, ZoneContent<P,A>[] zoneContents, Trimming[] trimmings, ShadeAxisKit[] shadeKits, PaperTypeSelector ptSel, Compositor compositor, PlotCaching caching)
Constructs a PlotScene containing multiple plot surfaces.

The zoneContents 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
  `zoneContents` - plot content with initial aspect by zone (nz-element array)
  `trimmings` - plot decoration specification by zone (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
  `caching` - plot caching policy

### PlotScene

public PlotScene(SurfaceFactory<P,A> surfFact, ZoneContent<P,A> content, Trimming trimming, ShadeAxisKit shadeKit, PaperTypeSelector ptSel, Compositor compositor, Padding padding, PlotCaching caching)
Constructs a PlotScene containing a single plot surface.

Parameters:
  `surfFact` - surface factory
  `content` - plot content with initial aspect
  `trimming` - specification of additional decoration
  `shadeKit` - shader axis specifier, or null if not required
  `ptSel` - paper type selector
  `compositor` - compositor for pixel composition
  `padding` - user requirements for external space
  `caching` - plot caching policy

## Method Details

### getGanger

public Ganger<P,A> getGanger()
Returns the Ganger used by this scene.

Returns:
  ganger

### getGang

public Gang getGang()
Returns the current plot gang.

Returns:
  gang

### getLayers

public PlotLayer[] getLayers(int iz)
Returns the plot layers contained in a given zone.

Parameters:
  `iz` - zone index
Returns:
  plot layers

### clearPlot

public void clearPlot()
Clears the current cached plot image, if any, so that regeneration of the image from the data is forced when the next paint operation is performed; otherwise it may be copied from a cached image.

### prepareScene

@Slow public void prepareScene(Rectangle extBounds, DataStore dataStore)
Ensures that the plot surfaces are ready to plot this scene. This method is invoked by `paintScene(Graphics, Rectangle, DataStore)`, but may be invoked directly if only the preparation and not the plotting itself is required.

Parameters:
  `extBounds` - external bounds of the plot, including any space required for axis labels, legend, padding etc
  `dataStore` - data storage object

### paintScene

@Slow public void paintScene(Graphics g, Rectangle extBounds, DataStore dataStore)
Paints the contents of this plot to a graphics context.

Parameters:
  `g` - graphics context
  `extBounds` - external bounds of the plot, including any space required for axis labels, legend, padding etc
  `dataStore` - data storage object

### setAspects

public boolean setAspects(A[] aspects)
Sets the aspects of the plot zones. Note this method does not test or adjust the supplied aspects for consistency with the ganger.

Parameters:
  `aspects` - per-zone array of required aspects
Returns:
  true iff the call resulted in a material change of the scene (requiring a repaint)

### getAspects

public A[] getAspects()
Returns the most recently set aspects.

Returns:
  per-zone array of current aspects

### getSurfaces

public Surface[] getSurfaces()
Returns the current plot surfaces. They will have been generated by this display's SurfaceFactory. Elements may be null if they are not currently up to date (plot is in process of being repainted).

Returns:
  per-zone surface array

### getZoneIndex

public int getZoneIndex(Point pos)
Returns the index of the zone in whose data bounds a given point lies.

Parameters:
  `pos` - graphics position
Returns:
  index of zone containing pos, or -1 if none

### findClosestRows

@Slow public IndicatedRow[] findClosestRows(Surface surface, PlotLayer[] layers, Point point, DataStore dataStore)
Assembles and returns a list of row indexes that are plotted close to a given graphics position. May return null, if the thread is interrupted, or possibly under other circumstances.

Parameters:
  `surface` - plot surface on which layers are plotted
  `layers` - layers plotted
  `point` - graphics position to which the selection event refers
  `dataStore` - data storage object
Returns:
  per-layer array of closest dataset row objects

### createGangScene

@Slow public static <P,A> PlotScene<P,A> createGangScene(Ganger<P,A> ganger, SurfaceFactory<P,A> surfFact, PlotLayer[][] layerArrays, P[] profiles, ConfigMap[] aspectConfigs, Trimming[] trimmings, ShadeAxisKit[] shadeKits, PaperTypeSelector ptSel, Compositor compositor, DataStore dataStore, PlotCaching caching)
Utility method to construct a ganged PlotDisplay, with aspect obtained from a supplied config map. This will perform ranging from data if it is required; in that case, it may take time to execute.

The layerArrays, profiles and aspectConfigs arrays must have the same length as the ganger zone count. 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 grouping
  `surfFact` - surface factory
  `layerArrays` - per-zone layer arrays (nz-element array)
  `profiles` - per-zone profiles (nz-element array); should be result of ganger.adjustProfiles
  `aspectConfigs` - per-zone config map providing entries for surf.getAspectKeys (nz-element arrays)
  `trimmings` - plot decoration specification by zone (nz- or 1-element array,elements may be null)
  `shadeKits` - shader axis specifiers by zone (nz- or 1-element array, elements may be null)
  `ptSel` - paper type selector
  `compositor` - compositor for pixel composition
  `dataStore` - data storage object
  `caching` - plot caching policy on every repaint
Returns:
  new plot component

### calculateNonShadeSpans

@Slow public static Map<AuxScale,Span> calculateNonShadeSpans(PlotLayer[] layers, Surface surface, Object[] plans, DataStore dataStore)
Gathers requested ranging information from data, excluding the AuxScale.COLOR item (the aux shading axis). The result is a map with an entry for every AuxScale required by any of the submitted layers, apart from AuxScale.COLOR, which must be calculated separately.

Parameters:
  `layers` - plot layers
  `surface` - surface on which layers will be plotted
  `plans` - array of calculated plan objects, or null
  `dataStore` - data storage object
Returns:
  ranging information
See Also:
  - `calculateShadeSpan(List, ShadeAxisKit, Object[], DataStore)`
  - `AuxScale.COLOR`

### calculateShadeSpan

@Slow public static Span calculateShadeSpan(List<uk.ac.starlink.util.Bi<Surface, PlotLayer>> surfLayers, ShadeAxisKit shadeKit, Object[] plans, DataStore dataStore)
Gathers ranging information for the aux shading axis from data. The result is a Span relating to the AuxScale.COLOR scale.

Parameters:
  `surfLayers` - list of paired (surface,layer) items corresponding to the plot that will be performed
  `shadeKit` - specifies shader axis, or null
  `plans` - array of calculated plan objects, or null
  `dataStore` - data storage object
Returns:
  AuxScale.COLOR ranging information, or null if none is required by the surfLayers
See Also:
  - `AuxScale.COLOR`