at.tuwien.ifs.somtoolbox.visualization
Class AbstractBackgroundImageVisualizer

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

public abstract class AbstractBackgroundImageVisualizer
extends java.lang.Object
implements BackgroundImageVisualizer

This class provides basic support for classes implementing BackgroundImageVisualizer.

Version:
$Id: AbstractBackgroundImageVisualizer.java 4166 2011-02-13 12:49:02Z mayer $
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 java.lang.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
           
private  int defaultOpacity
           
protected  SharedSOMVisualisationData inputObjects
           
protected  java.util.logging.Logger log
          The standard log for visualisations to write to
protected  MapPNode map
           
static long MAX_CACHE_SIZE_MB
           
protected  java.lang.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  java.lang.String[] VISUALIZATION_DESCRIPTIONS
          Longer description for the visualiation variants.
protected  java.lang.String[] VISUALIZATION_NAMES
          The names of the visualisation variants.
protected  java.lang.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
CACHE_KEY_SECTION_SEPARATOR, DEFAULT_BACKGROUND_VISUALIZATION_SCALE
 
Constructor Summary
AbstractBackgroundImageVisualizer()
          Initialises the control panel, if GraphicsEnvironment.isHeadless() reports to be in a non-headless environment.
 
Method Summary
static java.lang.String buildCacheKey(java.lang.Object... parts)
           
protected  void checkNeededObjectsAvailable(GrowingSOM gsom)
           
protected  void checkVariantIndex(int index, java.lang.Class<?> klass)
           
static void clearVisualisationCache()
          Clears the visualisation cache
 int compareTo(BackgroundImageVisualizer o)
           
abstract  java.awt.image.BufferedImage createVisualization(int variantIndex, GrowingSOM gsom, int width, int height)
          Creates a visualisation image.
 java.awt.image.BufferedImage createVisualization(java.lang.String variantName, GrowingSOM gsom, int width, int height)
          Creates a visualisation for the given variant name.
protected  void drawBackground(int width, int height, java.awt.Graphics2D g)
          Draws a background image on the given graphics object, and sets the Composite according to the currentely set opacity value.
static java.lang.String escapeFileName(java.lang.String key)
           
private  java.lang.String getBasicCacheKey(GrowingSOM gsom, int currentVariant, int width, int height)
           
static LeastRecentelyUsedImageCache getCache()
           
protected  java.lang.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.
 java.lang.String getDefaultVisualisationFileName(int currentVariant)
          Generates the default file name for the current visualisation
static java.lang.String getDefaultVisualisationFileName(java.lang.String cacheKey)
           
 java.lang.String getHTMLVisualisationControl(java.util.Map params)
          Returns HTML control elements (inputs) to be used by the webserver version of the SOM.
 int getNumberOfVisualizations()
           
private  java.lang.String getOpacityCacheKeyComponent()
           
 int getPreferredScaleFactor()
          Default implementation returning preferredScaleFactor.
protected  SOMToolboxException getVariantException(int index, java.lang.Class<?> klass)
           
protected  java.lang.String getVisualisationSpecificCacheKey(int currentVariant)
           
 java.awt.image.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.
 java.lang.String getVisualizationDescription(int index)
          Gets the descriptions of a specified visualisation variant.
 java.lang.String[] getVisualizationDescriptions()
          Gets the descriptions of all visualisation variants provided by this visualiser.
 java.util.HashMap<java.lang.String,java.awt.image.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.
 java.util.HashMap<java.lang.String,java.awt.image.BufferedImage> getVisualizationFlavours(int index, GrowingSOM gsom, int width, int height, int maxFlavours)
          Default implementation equal to getVisualizationFlavours(int, GrowingSOM, int, int).
 java.util.HashMap<java.lang.String,java.awt.image.BufferedImage> getVisualizationFlavours(int index, GrowingSOM gsom, int width, int height, java.util.Map<java.lang.String,java.lang.String> flavourParameters)
          Default implementation equal to getVisualizationFlavours(int, GrowingSOM, int, int).
 java.lang.String getVisualizationName(int index)
          Gets the name of a specified visualisation variant.
 java.lang.String[] getVisualizationNames()
          Gets the names of all visualisation variants provided by this visualiser.
 java.lang.String getVisualizationShortName(int index)
          Gets the short name of a specified visualisation variant.
 java.lang.String[] getVisualizationShortNames()
          Gets the short names of all visualisation variants provided by this visualiser.
protected  void invalidateCache(java.lang.String visualizationName)
          Deletes all cached elements from the given visualisation.
protected  void logImageCache(java.lang.String cacheKey)
           
 java.lang.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

protected static final java.lang.String CACHE_KEY_SEPARATOR
See Also:
Constant Field Values

MAX_CACHE_SIZE_MB

public static final long MAX_CACHE_SIZE_MB

NUM_VISUALIZATIONS

protected int NUM_VISUALIZATIONS
The number of visualisation variants this visualizer provides


VISUALIZATION_NAMES

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


VISUALIZATION_SHORT_NAMES

protected java.lang.String[] VISUALIZATION_SHORT_NAMES

VISUALIZATION_DESCRIPTIONS

protected java.lang.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 java.util.logging.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 java.lang.String[] neededInputObjects

map

protected MapPNode map

defaultOpacity

private int defaultOpacity

opacity

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


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 final java.lang.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.


getDefaultVisualisationFileName

public final java.lang.String getDefaultVisualisationFileName(int currentVariant)
Description copied from interface: BackgroundImageVisualizer
Generates the default file name for the current visualisation

Specified by:
getDefaultVisualisationFileName in interface BackgroundImageVisualizer

getDefaultVisualisationFileName

public static final java.lang.String getDefaultVisualisationFileName(java.lang.String cacheKey)

escapeFileName

public static java.lang.String escapeFileName(java.lang.String key)

getVisualisationSpecificCacheKey

protected java.lang.String getVisualisationSpecificCacheKey(int currentVariant)

getBasicCacheKey

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

getOpacityCacheKeyComponent

private java.lang.String getOpacityCacheKeyComponent()

getVisualization

public java.awt.image.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(java.lang.String cacheKey)

buildCacheKey

public static java.lang.String buildCacheKey(java.lang.Object... parts)

invalidateCache

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


createVisualization

public abstract java.awt.image.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 java.awt.image.BufferedImage createVisualization(java.lang.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,
                                 java.lang.Class<?> klass)
                          throws SOMToolboxException
Throws:
SOMToolboxException

getVariantException

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

getVisualizationDescription

public java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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 java.lang.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,
                              java.awt.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 java.lang.String getHTMLVisualisationControl(java.util.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 java.lang.Comparable<BackgroundImageVisualizer>

getVisualizationFlavours

public java.util.HashMap<java.lang.String,java.awt.image.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 java.util.HashMap<java.lang.String,java.awt.image.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 java.util.HashMap<java.lang.String,java.awt.image.BufferedImage> getVisualizationFlavours(int index,
                                                                                                 GrowingSOM gsom,
                                                                                                 int width,
                                                                                                 int height,
                                                                                                 java.util.Map<java.lang.String,java.lang.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


getCache

public static LeastRecentelyUsedImageCache getCache()
Returns:
Returns the cache.