Package sim.util.gui

Class SimpleColorMap

java.lang.Object
sim.util.gui.SimpleColorMap
All Implemented Interfaces:
ColorMap

public class SimpleColorMap extends Object implements ColorMap
Maps numerical levels to colors using either a lookup table, color interpolation, or both. A simple implementation of the ColorMap interface.
  1. Method 1: a color table. The user can provide an array of Colors; if the numerical value, cast into an integer, is between 0 and (the length of this array - 1), then the appropriate Color is returned.
  2. Method 2: color interpolation. The user can provide a min-level, min-Color, max-level, and max-Color. If the numerical value is below min-level, then minColor is provided. If it's above max-level, then max-Color is provided. If it's between min-level and max-level, then a linear interpolation between min-Color and max-Color is provided.

    You can customize the interpolation by overriding the transformLevel(...) method. This method receives a level value and the minimum and maximum values before it's clamped to a minimum or maximum color; you can modify this level value and return a new value (ideally between the minimum and maximum). For example, you could move the values to a log of their previous values.

    The default of transformLevel(...) calls another optional function you can override: the filterLevel(...) method. This method is passed a level value which has been pre-transformed such that 0.0 is the "minimum" and 1.0 is the "maximum". You can override this method to return a new value between 0.0 and 1.0 which will be "de-transformed" and used instead. The default simply returns the value itself.

    You should only override transformLevel(...), of filterLevel(...), or none, but not both.

The user can provide both a color table and an interpolation; in this case, the color table takes precedence over the interpolation in that region where the color table is relevant. You specify a color table with setColorTable(), and you specify an interpolation range with setLevels(). It's important to note that transformLevel(...) and filterLevel(...) are not applied to the color table, only to the interpolation. So if you provide 2.7 as a level, and have some fancy-shmancy transformation for that in transformLevel(...), but you've made a color table 5 elements long, color number 2 will be used directly without every checking your transformLevel(...) method.

validLevel() is set to return true if the level range is between min-level and max-level, or if it's inside the color table range. Neither transformLevel(...) nor filterLevel(...) are called.

defaultValue() is set to return 0 if the color table exists, else min-level is provided.

NaN is assumed to be the same color as negative infinity.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    User-provided color table
  • Constructor Summary

    Constructors
    Constructor
    Description
    Constructs a ColorMap that gradiates from 0.0 -> black to 1.0 -> white.
    SimpleColorMap(double minLevel, double maxLevel, Color minColor, Color maxColor)
    Constructs a ColorMap that gradiates from minLevel -> minColor to maxLevel -> maxColor.
    SimpleColorMap(Color[] colorTable)
    Given an array of size n, constructs a ColorMap that maps integers from 0 to n-1 to the colors in the array.
    SimpleColorMap(Color[] colorTable, double minLevel, double maxLevel, Color minColor, Color maxColor)
    Given an array of size n, constructs a ColorMap that maps integers from 0 to n-1 to the colors in the array, and gradiates from minLevel -> minColor to maxLevel -> maxColor for certain other values.
  • Method Summary

    Modifier and Type
    Method
    Description
    double
    Returns some level which is valid (that is, validLevel(defaultValue()) should always return true).
    double
    filterLevel(double level)
    Override this to convert level values to new values using some appropriate mathematical transformation.
    int
    getAlpha(double level)
    Returns the alpha value for a color for the given level.
    getColor(double level)
    Returns a color for the given level
    int
    getRGB(double level)
    Returns the RGB values, plus alpha, for a color for the given level.
    setColorTable(Color[] colorTable)
    Specifies that if a value (cast into an int) in the IntGrid2D or DoubleGrid2D falls in the range 0 ...
    void
    setLevels(double minLevel, double maxLevel, Color minColor, Color maxColor)
    Sets the color levels for the ValueGridPortrayal2D values for use by the default getColor(...) method.
    double
    transformLevel(double level, double minLevel, double maxLevel)
    Override this to convert level values to new values using some appropriate mathematical transformation.
    boolean
    validLevel(double value)
    Returns true if a level is "valid" (it provides a meaningful color)

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
  • Field Details

    • colors

      public Color[] colors
      User-provided color table
  • Constructor Details

    • SimpleColorMap

      public SimpleColorMap()
      Constructs a ColorMap that gradiates from 0.0 -> black to 1.0 -> white. Values higher than 1.0 are mapped to white. Values less than 0.0 are mapped to black. Values from 0.0 through 1.0 are considered valid levels by validLevel(...). The default value is 0.0 (for defaultValue() ).
    • SimpleColorMap

      public SimpleColorMap(double minLevel, double maxLevel, Color minColor, Color maxColor)
      Constructs a ColorMap that gradiates from minLevel -> minColor to maxLevel -> maxColor. Values higher than maxLevel are mapped to maxColor. Values less than minLevel are mapped to minColor. Values from minLevel through maxLevel are considered valid levels by validLevel(...). The default value is minLevel (for defaultValue() ).
    • SimpleColorMap

      public SimpleColorMap(Color[] colorTable)
      Given an array of size n, constructs a ColorMap that maps integers from 0 to n-1 to the colors in the array. Any real-valued number x, for 0 invalid input: '<'= x invalid input: '<' n, is converted into an integer (with floor()) and then mapped to an array color. For all other values, clear is returned. Values from x through n, not including n, are considered valid levels by validLevel(...). The default value is 0 (for defaultValue() ).
    • SimpleColorMap

      public SimpleColorMap(Color[] colorTable, double minLevel, double maxLevel, Color minColor, Color maxColor)
      Given an array of size n, constructs a ColorMap that maps integers from 0 to n-1 to the colors in the array, and gradiates from minLevel -> minColor to maxLevel -> maxColor for certain other values. Any real-valued number x, for 0 invalid input: '<'= x invalid input: '<' n, is converted into an integer (with floor()) and then mapped to an array color. Outside this range, gradiation occurs for minLevel invalid input: '<'= x invalid input: '<'= maxLevel. For any other value of x, values higher than maxLevel are mapped to maxColor, and values less than minLevel are mapped to minColor. Values from x through n, not including n, and additionally values from minLevel through maxLevel, are considered valid levels by validLevel(...) The default value is 0 (for defaultValue() ).
  • Method Details

    • setColorTable

      public Color[] setColorTable(Color[] colorTable)
      Specifies that if a value (cast into an int) in the IntGrid2D or DoubleGrid2D falls in the range 0 ... colors.length, then that index in the colors table should be used to represent that value. Otherwise, values in setLevels(...) are used. You can remove the color table by passing in null here. Returns the old color table.
    • filterLevel

      public double filterLevel(double level)
      Override this to convert level values to new values using some appropriate mathematical transformation. The provided level value will be scaled to between 0 and 1 inclusive, which represent the minimum and maximum possible colors. The value you return must also be between 0 and 1 inclusive. The default version of this function just returns the level.

      Do not override both this function and transformLevel(...). transformLevel simply calls this function.

    • transformLevel

      public double transformLevel(double level, double minLevel, double maxLevel)
      Override this to convert level values to new values using some appropriate mathematical transformation. The values you return ought to be >= minLevel and invalid input: '<'= maxLevel; values outside these bounds will be trimmed to minLevel or maxLevel respectively prior to conversion to a color. The default implementation simply returns the passed-in level. The default version scales level to a range between 0 and 1 in such a way that minLevel is 0 and maxLevel is 1; it then calls filterLevel, then un-scales the result and returns it.

      Do not override both this function and filterLevel(...). filterLevel is just used by this function.

    • setLevels

      public void setLevels(double minLevel, double maxLevel, Color minColor, Color maxColor)
      Sets the color levels for the ValueGridPortrayal2D values for use by the default getColor(...) method. These are overridden by any array provided in setColorTable(). If the value in the IntGrid2D or DoubleGrid2D is less than or equal to minLevel, then minColor is used. If the value is greater than or equal to maxColor, then maxColor is used. Otherwise a linear interpolation from minColor to maxColor is used.
    • getColor

      public Color getColor(double level)
      Description copied from interface: ColorMap
      Returns a color for the given level
      Specified by:
      getColor in interface ColorMap
    • getAlpha

      public int getAlpha(double level)
      Description copied from interface: ColorMap
      Returns the alpha value for a color for the given level. This could be simply written as

      return getRGB(level) >>> 24 ;

      ...or it could be written as:

      return getColor(level).getAlpha()

      ...however it's likely that it this method could be written more efficiently than either of these.

      Specified by:
      getAlpha in interface ColorMap
    • getRGB

      public int getRGB(double level)
      Description copied from interface: ColorMap
      Returns the RGB values, plus alpha, for a color for the given level. The byte ordering should be in the same fashion that Color.getRGB() is provided. This could be simply written as

      invalid input: '<'code return getColor(level).getRGB() ... however it's likely that this method could be written more efficiently than this.

      Why isn't this called getRGBA(...)? Because for some reason the underlying Color method is likewise getRGB(), even though it ought to be called getRGBA().

      Specified by:
      getRGB in interface ColorMap
    • validLevel

      public boolean validLevel(double value)
      Description copied from interface: ColorMap
      Returns true if a level is "valid" (it provides a meaningful color)
      Specified by:
      validLevel in interface ColorMap
    • defaultValue

      public double defaultValue()
      Description copied from interface: ColorMap
      Returns some level which is valid (that is, validLevel(defaultValue()) should always return true). This is commonly provided to give the user a level to replace an "invalid" level he's typed in.
      Specified by:
      defaultValue in interface ColorMap