at.tuwien.ifs.somtoolbox.visualization
Class AbstractBackgroundImageVisualizer

java.lang.Object
  extended by at.tuwien.ifs.somtoolbox.visualization.AbstractBackgroundImageVisualizer
All Implemented Interfaces:
BackgroundImageVisualizer, Comparable<BackgroundImageVisualizer>
Direct Known Subclasses:
AbstractMatrixVisualizer, CategoryPieChartVisualizer, ClusterConnectionsVisualizer, FlowBorderlineVisualizer, FuzzyColourCodingVisualiser, IntrinsicDistanceVisualizer, MappingDistortionVisualizer, MetroMapVisualizer, MinimumSpanningTreeVisualizer, NeighbourhoodGraph, ThematicClassMapVisualizer, TopographicErrorVisualizer, TopographicProductVisualizer, TrustwothinessVisualizer

public abstract class AbstractBackgroundImageVisualizer
extends Object
implements BackgroundImageVisualizer

This class provides basic support for classes implementing BackgroundImageVisualizer.

Version:
$Id: AbstractBackgroundImageVisualizer.java 3888 2010-11-02 17:42:53Z frank $
Author:
Michael Dittenbach, Rudolf Mayer

Nested Class Summary
protected static class AbstractBackgroundImageVisualizer.ContourInterpolationMode
           
protected static class AbstractBackgroundImageVisualizer.ContourMode
           
 class AbstractBackgroundImageVisualizer.VisualizationControlPanel
          A basic visualisation control panel, providing a JSpinner to control the opacity.
 
Field Summary
protected static LeastRecentelyUsedImageCache cache
          The cache of generated images, to allow faster switching between different visualisations and palettes.
protected static String CACHE_KEY_SECTION_SEPARATOR
           
static String CACHE_KEY_SEPARATOR
           
protected  AbstractBackgroundImageVisualizer.ContourInterpolationMode contourInterpolationMode
           
protected  AbstractBackgroundImageVisualizer.ContourMode contourMode
           
protected  AbstractBackgroundImageVisualizer.VisualizationControlPanel controlPanel
          The panel to control the behaviour of the visualisation.
 int currentZDimSlice
           
protected  SharedSOMVisualisationData inputObjects
           
protected  boolean interpolate
           
protected  Logger log
          The standard log for visualisations to write to
protected  MapPNode map
           
static long MAX_CACHE_SIZE_MB
           
protected  String[] neededInputObjects
           
protected  int NUM_VISUALIZATIONS
          The number of visualisation variants this visualizer provides
protected  int numberOfContours
           
protected  int opacity
          The opacity (transparency) value for this visualisation.
protected  int preferredScaleFactor
          Initialised with the default value from BackgroundImageVisualizer.DEFAULT_BACKGROUND_VISUALIZATION_SCALE.
protected  String[] VISUALIZATION_DESCRIPTIONS
          Longer description for the visualiation variants.
protected  String[] VISUALIZATION_NAMES
          The names of the visualisation variants.
protected  String[] VISUALIZATION_SHORT_NAMES
           
protected  VisualizationUpdateListener visualizationUpdateListener
          The listener registered to act on changing visualisation variants or other properties.
 int zSize
           
 
Fields inherited from interface at.tuwien.ifs.somtoolbox.visualization.BackgroundImageVisualizer
DEFAULT_BACKGROUND_VISUALIZATION_SCALE
 
Constructor Summary
AbstractBackgroundImageVisualizer()
          Initialises the control panel, if GraphicsEnvironment.isHeadless() reports to be in a non-headless environment.
 
Method Summary
 String appendToCacheKey(GrowingSOM gsom, int currentVariant, int width, int height, Object... parts)
           
static String buildCacheKey(Object... parts)
           
protected  void checkNeededObjectsAvailable(GrowingSOM gsom)
           
protected  void checkVariantIndex(int index, Class<?> klass)
           
static void clearVisualisationCache()
          Clears the visualisation cache
 int compareTo(BackgroundImageVisualizer o)
           
abstract  BufferedImage createVisualization(int variantIndex, GrowingSOM gsom, int width, int height)
          Creates a visualisation image.
 BufferedImage createVisualization(String variantName, GrowingSOM gsom, int width, int height)
          Creates a visualisation for the given variant name.
protected  void drawBackground(int width, int height, Graphics2D g)
          Draws a background image on the given graphics object, and sets the Composite according to the currentely set opacity value.
private  String getBasicCacheKey(GrowingSOM gsom, int currentVariant, int width, int height)
           
protected  String getCacheKey(GrowingSOM gsom, int currentVariant, int width, int height)
          The key of a cache is created as follows: VisualisationShortName + Hashcode of the SOM + Width + Height + Opacity.
Sub-classes might add more information to the cache, if needed.
 AbstractBackgroundImageVisualizer.VisualizationControlPanel getControlPanel()
          Gets the visualisation control panel.
 String getHTMLVisualisationControl(Map params)
          Returns HTML control elements (inputs) to be used by the webserver version of the SOM.
 int getNumberOfVisualizations()
           
 int getPreferredScaleFactor()
          Default implementation returning preferredScaleFactor.
protected  SOMToolboxException getVariantException(int index, Class<?> klass)
           
 BufferedImage getVisualization(int index, GrowingSOM gsom, int width, int height)
          Returns the requested visualization image, either by retrieving it from the image cache, or by invoking createVisualization(int, GrowingSOM, int, int) to create the image new.
 String getVisualizationDescription(int index)
          Gets the descriptions of a specified visualisation variant.
 String[] getVisualizationDescriptions()
          Gets the descriptions of all visualisation variants provided by this visualiser.
 HashMap<String,BufferedImage> getVisualizationFlavours(int index, GrowingSOM gsom, int width, int height)
          Default implementation which returns a map of size 1 with the standard, unparameterised visualisation of the given variant.
 HashMap<String,BufferedImage> getVisualizationFlavours(int index, GrowingSOM gsom, int width, int height, int maxFlavours)
          Default implementation equal to getVisualizationFlavours(int, GrowingSOM, int, int).
 HashMap<String,BufferedImage> getVisualizationFlavours(int index, GrowingSOM gsom, int width, int height, Map<String,String> flavourParameters)
          Default implementation equal to getVisualizationFlavours(int, GrowingSOM, int, int).
 String getVisualizationName(int index)
          Gets the name of a specified visualisation variant.
 String[] getVisualizationNames()
          Gets the names of all visualisation variants provided by this visualiser.
 String getVisualizationShortName(int index)
          Gets the short name of a specified visualisation variant.
 String[] getVisualizationShortNames()
          Gets the short names of all visualisation variants provided by this visualiser.
protected  void invalidateCache(String visualizationName)
          Deletes all cached elements from the given visualisation.
protected  void logImageCache(String cacheKey)
           
 String[] needsAdditionalFiles()
          Checks whether this visualisation still needs some input files to generate an image.
 void setInputObjects(SharedSOMVisualisationData inputObjects)
          Implementing sub-classes shall override this method if they need to set some specific input object related information.
 void setMap(MapPNode map)
          Sets the map this visualiser operates on.
 void setSOMData(SOMInputReader reader)
          Implementing sub-classes shall override this method if they need to set some specific input-data related information.
 void setVisualizationUpdateListener(VisualizationUpdateListener listener)
          Sets a new listener for visualisation update events.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

CACHE_KEY_SEPARATOR

public static final String CACHE_KEY_SEPARATOR
See Also:
Constant Field Values

MAX_CACHE_SIZE_MB

public static final long MAX_CACHE_SIZE_MB

CACHE_KEY_SECTION_SEPARATOR

protected static final String CACHE_KEY_SECTION_SEPARATOR
See Also:
Constant Field Values

NUM_VISUALIZATIONS

protected int NUM_VISUALIZATIONS
The number of visualisation variants this visualizer provides


VISUALIZATION_NAMES

protected String[] VISUALIZATION_NAMES
The names of the visualisation variants.


VISUALIZATION_SHORT_NAMES

protected String[] VISUALIZATION_SHORT_NAMES

VISUALIZATION_DESCRIPTIONS

protected String[] VISUALIZATION_DESCRIPTIONS
Longer description for the visualiation variants. Can e.g. be references to the algorithm, etc.


controlPanel

protected AbstractBackgroundImageVisualizer.VisualizationControlPanel controlPanel
The panel to control the behaviour of the visualisation.


cache

protected static final LeastRecentelyUsedImageCache cache
The cache of generated images, to allow faster switching between different visualisations and palettes. Note that the cache is static, i.e. only one cache for all visualisation subclasses is used.


log

protected Logger log
The standard log for visualisations to write to


visualizationUpdateListener

protected VisualizationUpdateListener visualizationUpdateListener
The listener registered to act on changing visualisation variants or other properties.


inputObjects

protected SharedSOMVisualisationData inputObjects

neededInputObjects

protected String[] neededInputObjects

map

protected MapPNode map

opacity

protected int opacity
The opacity (transparency) value for this visualisation. 100 means no transparency, while 0 means total transparency.


interpolate

protected boolean interpolate

contourMode

protected AbstractBackgroundImageVisualizer.ContourMode contourMode

numberOfContours

protected int numberOfContours

contourInterpolationMode

protected AbstractBackgroundImageVisualizer.ContourInterpolationMode contourInterpolationMode

zSize

public int zSize

currentZDimSlice

public int currentZDimSlice

preferredScaleFactor

protected int preferredScaleFactor
Initialised with the default value from BackgroundImageVisualizer.DEFAULT_BACKGROUND_VISUALIZATION_SCALE. Visualisations that need a specific scale shall set this value differently (e.g. in the constructor), or overwrite getPreferredScaleFactor()

Constructor Detail

AbstractBackgroundImageVisualizer

public AbstractBackgroundImageVisualizer()
Initialises the control panel, if GraphicsEnvironment.isHeadless() reports to be in a non-headless environment.

Method Detail

getCacheKey

protected String getCacheKey(GrowingSOM gsom,
                             int currentVariant,
                             int width,
                             int height)
The key of a cache is created as follows: VisualisationShortName + Hashcode of the SOM + Width + Height + Opacity.
Sub-classes might add more information to the cache, if needed.


getBasicCacheKey

private String getBasicCacheKey(GrowingSOM gsom,
                                int currentVariant,
                                int width,
                                int height)

getVisualization

public BufferedImage getVisualization(int index,
                                      GrowingSOM gsom,
                                      int width,
                                      int height)
                               throws SOMToolboxException
Returns the requested visualization image, either by retrieving it from the image cache, or by invoking createVisualization(int, GrowingSOM, int, int) to create the image new. Subclasses should not overwrite this method, unless they implement their own caching mechanism, or do not want any caching.

Specified by:
getVisualization in interface BackgroundImageVisualizer
Parameters:
index - the index of the variant to use
gsom - the GrowingSOM to take build the visualisation for
width - the desired width of the image, in pixels
height - the desired height of the image, in pixels
Returns:
an image for this visualisation
Throws:
SOMToolboxException - If there was an error creating the visualisation
See Also:
BackgroundImageVisualizer.getVisualization(int, at.tuwien.ifs.somtoolbox.models.GrowingSOM, int, int)

logImageCache

protected void logImageCache(String cacheKey)

appendToCacheKey

public String appendToCacheKey(GrowingSOM gsom,
                               int currentVariant,
                               int width,
                               int height,
                               Object... parts)

buildCacheKey

public static String buildCacheKey(Object... parts)

invalidateCache

protected void invalidateCache(String visualizationName)
Deletes all cached elements from the given visualisation.


createVisualization

public abstract BufferedImage createVisualization(int variantIndex,
                                                  GrowingSOM gsom,
                                                  int width,
                                                  int height)
                                           throws SOMToolboxException
Creates a visualisation image. Subclasses must implement this method.

Parameters:
variantIndex - the index of the variant to use
gsom - the GrowingSOM to take build the visualisation for
width - the desired width of the image, in pixels
height - the desired height of the image, in pixels.
Returns:
an image for this visualisation.
Throws:
SOMToolboxException

createVisualization

public BufferedImage createVisualization(String variantName,
                                         GrowingSOM gsom,
                                         int width,
                                         int height)
                                  throws SOMToolboxException
Creates a visualisation for the given variant name. Basically just a call to createVisualization(int, GrowingSOM, int, int), but throws a SOMToolboxException if the given variant name is not known in either the VISUALIZATION_NAMES nor VISUALIZATION_SHORT_NAMES.

Throws:
SOMToolboxException

getNumberOfVisualizations

public int getNumberOfVisualizations()
Specified by:
getNumberOfVisualizations in interface BackgroundImageVisualizer
Returns:
Returns the number of visualizations

checkVariantIndex

protected void checkVariantIndex(int index,
                                 Class<?> klass)
                          throws SOMToolboxException
Throws:
SOMToolboxException

getVariantException

protected SOMToolboxException getVariantException(int index,
                                                  Class<?> klass)

getVisualizationDescription

public String getVisualizationDescription(int index)
Description copied from interface: BackgroundImageVisualizer
Gets the descriptions of a specified visualisation variant.

Specified by:
getVisualizationDescription in interface BackgroundImageVisualizer
Parameters:
index - the index of the variant to use
Returns:
the description of the visualisation variant

getVisualizationDescriptions

public String[] getVisualizationDescriptions()
Description copied from interface: BackgroundImageVisualizer
Gets the descriptions of all visualisation variants provided by this visualiser.

Specified by:
getVisualizationDescriptions in interface BackgroundImageVisualizer
Returns:
a String array containing all descriptions

getVisualizationName

public String getVisualizationName(int index)
Description copied from interface: BackgroundImageVisualizer
Gets the name of a specified visualisation variant.

Specified by:
getVisualizationName in interface BackgroundImageVisualizer
Parameters:
index - the index of the variant to use
Returns:
the name of the visualisation variant

getVisualizationNames

public String[] getVisualizationNames()
Description copied from interface: BackgroundImageVisualizer
Gets the names of all visualisation variants provided by this visualiser.

Specified by:
getVisualizationNames in interface BackgroundImageVisualizer
Returns:
a String array containing all names

getVisualizationShortName

public String getVisualizationShortName(int index)
Description copied from interface: BackgroundImageVisualizer
Gets the short name of a specified visualisation variant.

Specified by:
getVisualizationShortName in interface BackgroundImageVisualizer
Parameters:
index - the index of the variant to use
Returns:
the short name of the visualisation variant

getVisualizationShortNames

public String[] getVisualizationShortNames()
Description copied from interface: BackgroundImageVisualizer
Gets the short names of all visualisation variants provided by this visualiser.

Specified by:
getVisualizationShortNames in interface BackgroundImageVisualizer
Returns:
a String array containing all short names

needsAdditionalFiles

public String[] needsAdditionalFiles()
Description copied from interface: BackgroundImageVisualizer
Checks whether this visualisation still needs some input files to generate an image.

Specified by:
needsAdditionalFiles in interface BackgroundImageVisualizer
Returns:
an array containing the names of the input objects needed

checkNeededObjectsAvailable

protected void checkNeededObjectsAvailable(GrowingSOM gsom)
                                    throws SOMToolboxException
Throws:
SOMToolboxException

getControlPanel

public AbstractBackgroundImageVisualizer.VisualizationControlPanel getControlPanel()
Description copied from interface: BackgroundImageVisualizer
Gets the visualisation control panel.

Specified by:
getControlPanel in interface BackgroundImageVisualizer
Returns:
the control panel of this visualizer

setVisualizationUpdateListener

public void setVisualizationUpdateListener(VisualizationUpdateListener listener)
Description copied from interface: BackgroundImageVisualizer
Sets a new listener for visualisation update events.

Specified by:
setVisualizationUpdateListener in interface BackgroundImageVisualizer
Parameters:
listener - the new listener to be registered

setInputObjects

public void setInputObjects(SharedSOMVisualisationData inputObjects)
Implementing sub-classes shall override this method if they need to set some specific input object related information.

Specified by:
setInputObjects in interface BackgroundImageVisualizer
Parameters:
inputObjects - the new input objects
See Also:
SOMVisualisationData

setSOMData

public void setSOMData(SOMInputReader reader)
Implementing sub-classes shall override this method if they need to set some specific input-data related information.

Specified by:
setSOMData in interface BackgroundImageVisualizer
Parameters:
reader - the som input reader

setMap

public void setMap(MapPNode map)
Description copied from interface: BackgroundImageVisualizer
Sets the map this visualiser operates on.

Specified by:
setMap in interface BackgroundImageVisualizer
Parameters:
map - the map

drawBackground

protected void drawBackground(int width,
                              int height,
                              Graphics2D g)
Draws a background image on the given graphics object, and sets the Composite according to the currentely set opacity value.

Parameters:
width - the desired width of the background image, in pixels
height - the desired height of the background image, in pixels
g - the graphics to draw on.

getHTMLVisualisationControl

public String getHTMLVisualisationControl(Map params)
Description copied from interface: BackgroundImageVisualizer
Returns HTML control elements (inputs) to be used by the webserver version of the SOM. Only the inputs are required, the surrounding form will be provided.

Specified by:
getHTMLVisualisationControl in interface BackgroundImageVisualizer
Parameters:
params - the parameters as passed by the web request - used to select the values in the inputs.
Returns:
HTML code containing the inputs

getPreferredScaleFactor

public int getPreferredScaleFactor()
Default implementation returning preferredScaleFactor. Visualisations that need a specific scale factor shall set the value of this field differently (e.g. in their constructor), or overwrite this method.

Specified by:
getPreferredScaleFactor in interface BackgroundImageVisualizer

compareTo

public int compareTo(BackgroundImageVisualizer o)
Specified by:
compareTo in interface Comparable<BackgroundImageVisualizer>

getVisualizationFlavours

public HashMap<String,BufferedImage> getVisualizationFlavours(int index,
                                                              GrowingSOM gsom,
                                                              int width,
                                                              int height)
                                                       throws SOMToolboxException
Default implementation which returns a map of size 1 with the standard, unparameterised visualisation of the given variant. Subclasses that want to return more flavours should override this method.

Specified by:
getVisualizationFlavours in interface BackgroundImageVisualizer
Throws:
SOMToolboxException

getVisualizationFlavours

public HashMap<String,BufferedImage> getVisualizationFlavours(int index,
                                                              GrowingSOM gsom,
                                                              int width,
                                                              int height,
                                                              int maxFlavours)
                                                       throws SOMToolboxException
Default implementation equal to getVisualizationFlavours(int, GrowingSOM, int, int).

Specified by:
getVisualizationFlavours in interface BackgroundImageVisualizer
Throws:
SOMToolboxException

getVisualizationFlavours

public HashMap<String,BufferedImage> getVisualizationFlavours(int index,
                                                              GrowingSOM gsom,
                                                              int width,
                                                              int height,
                                                              Map<String,String> flavourParameters)
                                                       throws SOMToolboxException
Default implementation equal to getVisualizationFlavours(int, GrowingSOM, int, int).

Specified by:
getVisualizationFlavours in interface BackgroundImageVisualizer
Throws:
SOMToolboxException

clearVisualisationCache

public static void clearVisualisationCache()
Clears the visualisation cache