Package com.xinapse.image

Class ColourMapping

java.lang.Object
com.xinapse.image.ColourMapping
All Implemented Interfaces:
Cloneable, Icon
public class ColourMapping extends Object implements Icon, Cloneable
The ColourMapping class represents a mapping from pixel presentation values (PPVs) to colours that are shown on a display device, such as a computer monitor.

The class has a number of built-in colour mappings, and contains the methods to create custom colour mappings, and to import new ColourMappings from disk. This class also contains methods to convert from a set of pixel presentation values (pixel values) to colour values that should be displayed on screen.

Included is the capability to set the display characteristics (approximately) according to the DICOM Grayscale Standard Display Function, as described in Part 14 of the DICOM standards. This allows the two ColourMappings MONOCHROME1 and MONOCHROME2 to be set and updated according to local display conditions. The factors taken into account when setting these ColourMappings are:

  • The minimum luminance of the display under ambient lighting conditions.
  • The maximum luminance of the display under ambient lighting conditions.
  • The gamma chanracteristic of the display.
Given these three properties, the MONOCHROME1 and MONOCHROME2 ColourMappings are adjusted to give a mapping of pixel PPVs so that equal steps of PPV are given perceptually equal changes of image intensity.

The settings are stored in the user Preferences, on a host-by-host basis, and so should be set by every user for every computer that he or she uses.

N.B. no other ColourMappings are affected by the display settings.

This Class also implements Icon, so that the ColourMapping can be used to generate icons representing the ColourMapping.

  • Field Details

    • MIN_LUMINANCE

      public static final float MIN_LUMINANCE
      The minimum value of display luminance (for a DDL of zero) that is allowed (including ambient light).
      See Also:

    • MAX_LUMINANCE

      public static final float MAX_LUMINANCE
      The maximum value of display luminance (for a DDL of 255) that is allowed (including ambient light).
      See Also:

    • MIN_GAMMA

      public static final float MIN_GAMMA
      The minimum display gamma value that is allowed.
      See Also:

    • MAX_GAMMA

      public static final float MAX_GAMMA
      The maximum display gamma value that is allowed.
      See Also:

    • DEFAULT_MIN_LUMINANCE

      public static final float DEFAULT_MIN_LUMINANCE
      The default luminance of the computer display for a digital driver level (DDL) of zero, including the effects of ambient light.
      See Also:

    • DEFAULT_MAX_LUMINANCE

      public static final float DEFAULT_MAX_LUMINANCE
      The default luminance of the computer display for a digital driver level (DDL) of 255, including the effects of ambient light.
      See Also:

    • DEFAULT_GAMMA

      public static final float DEFAULT_GAMMA
      The default gamma value of the computer display. Display luminance (excluding the effect of ambient light) is assumed to be proportional to the DDL raised to the power of gamma.
      See Also:

    • MONOCHROME1

      public static final ColourMapping MONOCHROME1
      The ColourMapping representing a grey (white to black) intensity scale. Normally used for plain x-ray images.

    • MONOCHROME2

      public static final ColourMapping MONOCHROME2
      The ColourMapping representing a grey (black to white) intensity scale. Normally used for MRI and CT images.

    • HOBS

      public static final ColourMapping HOBS
      The ColourMapping representing a hot body (black to white via red) intensity scale.

    • RBOW1

      public static final ColourMapping RBOW1
      The ColourMapping representing a rainbow of colours intensity scale.

    • RBOW2

      public static final ColourMapping RBOW2
      The ColourMapping representing an alternative rainbow of colours intensity scale.

    • RED

      public static final ColourMapping RED
      The ColourMapping representing a red intensity scale.

    • GREEN

      public static final ColourMapping GREEN
      The ColourMapping representing a green intensity scale.

    • BLUE

      public static final ColourMapping BLUE
      The ColourMapping representing a blue intensity scale.

    • YELLOW

      public static final ColourMapping YELLOW
      The ColourMapping representing a yellow intensity scale.

    • CYAN

      public static final ColourMapping CYAN
      The ColourMapping representing a cyan intensity scale.

    • MAGENTA

      public static final ColourMapping MAGENTA
      The ColourMapping representing a magenta intensity scale.

    • STEP

      public static final ColourMapping STEP
      The ColourMapping representing a step change in intensity scale.

    • cm

      public IndexColorModel cm
      The IndexColorModel used to contain the mapping.

  • Method Details

    • getInstance

      public static ColourMapping getInstance(byte[] red, byte[] green, byte[] blue) throws InvalidColourMappingException
      Returns a ColourMapping object according to a set of red, green and blue gun values. If the ColourMapping is equivalent to one of the built-in ColourMappings, then the built-in is returned; otherwise a new ColourMapping is created and returned.
      Parameters:
      red - the red gun values for each slot in the ColourMapping.
      green - the green gun values for each slot in the ColourMapping.
      blue - the blue gun values for each slot in the ColourMapping.
      Returns:
      a ColourMapping from a set of red, green and blue gun values.
      Throws:
      InvalidColourMappingException - if the lengths of the red, green and blue arrays are unequal, or if the length of the arrays is greater than 256, or less than 1.

    • newInstance

      public static ColourMapping newInstance(String entriesString) throws InvalidColourMappingException
      Creates a new ColourMapping object from a String representation of the ColourMapping name, or the list of entries in the ColourMapping.
      Parameters:
      entriesString - a String representing either:
      • The entries in the ColourMapping which is of the form:
        {R1,G1,B1}{R2,G2,B2}..{RN,GN,BN}.
      • The name of a ColourMapping. Currently-recognised names are:
        • MONOCHROME1
        • MONOCHROME2
      Returns:
      a ColourMapping from a String representation of the ColourMapping name, or the list of entries in the ColourMapping.
      Throws:
      InvalidColourMappingException - if the entries in the ColourMapping cannot be parsed from the entriesString.

    • getInstance

      public static ColourMapping getInstance(String name) throws InvalidArgumentException
      Returns one of the "built-in" ColourMappings, selected according to its name. The case of the supplied name is ignored when selecting the mapping.

      Note: the name of a ColourMapping can be retrieved with the toString() method.

      Parameters:
      name - the name of the ColourMapping.
      Returns:
      one of the built-in ColourMappings, from its name.
      Throws:
      InvalidArgumentException - if the supplied name does not match any of the names of the built-in mappings.

    • getUserInstance

      public static ColourMapping getUserInstance(String name) throws InvalidArgumentException
      Returns one of the user-defined ColourMappings, selected according to its name. The case of the supplied name is ignored when selecting the mapping.

      Note: the name of a ColourMapping can be retrieved with the toString() method.

      Parameters:
      name - the name of the ColourMapping.
      Returns:
      one of the user-defined ColourMappings, from its name.
      Throws:
      InvalidArgumentException - if the supplied name does not match any of the names of the user-defined mappings, or there are no user-defined mappings.

    • getKnownInstance

      public static ColourMapping getKnownInstance(String name) throws InvalidArgumentException
      Returns one of "known" ColourMappings (either built-in or user-defined), selected according to its name. The case of the supplied name is ignored when selecting the mapping.

      Note: the name of a ColourMapping can be retrieved with the toString() method.

      Parameters:
      name - the name of the ColourMapping.
      Returns:
      one of the known ColourMappings, from its name.
      Throws:
      InvalidArgumentException - if the supplied name does not match any of the names of the known mappings.

    • invert

      public ColourMapping invert()
      Creates a new ColourMapping by inverting this ColourMapping.
      Returns:
      a new ColourMapping that is an inverted version of this one.

    • makeTransparent

      public ColourMapping makeTransparent(byte alpha, boolean transparentBackground)
      Add transparency (an alpha channel) to an existing ColourMapping.
      Parameters:
      alpha - the transparency value as un unsigned byte value.
      transparentBackground - if the background (colour values slot 0) is to be completely transparent.
      Returns:
      a new ColourMapping with the specified transparency (alpha channel). The same alpha applies to all entries in the ColourMapping.

    • addUserColourMapping

      public static ColourMapping addUserColourMapping(Component parentComponent) throws InvalidColourMappingException, FileNotFoundException, IOException, CancelledException
      Prompts the user to add a new user-defined ColourMapping. A JFileChooser will pop up allowing the user to select the file containing the ColourMapping, followed by an input dialog allowing the user to set the name of the ColourMapping.

      The new ColourMapping is added to the list maintained in the user preferences.

      Parameters:
      parentComponent - the Component that will be used to position the JFileChooser.
      Returns:
      a user-defined ColourMapping selected by the user.
      Throws:
      InvalidColourMappingException - if the file format is bad.
      FileNotFoundException - if the supplied filename cannot be found.
      IOException - if an I/O error occurs.
      CancelledException - if the user cancels the operation.

    • deleteUserColourMapping

      public static void deleteUserColourMapping(ColourMapping colourMapping)
      Deletes one of the user-defined ColourMappings and removes it from the list maintained in the user preferences.

      If the supplied ColourMapping is not one of the current user-defined ColourMappings, this method does nothing.

      Parameters:
      colourMapping - the ColourMappings to be removed.

    • colourLookup

      public void colourLookup(int nCols, int nRows, Object pixValues, int offset, PixelDataType dataType, byte[] bytePixel, double min, double max, boolean inverted, BitSet mask, boolean interpolate, ComplexMode complexMode) throws IllegalArgumentException
      Converts an array of pixel intensity values into the byte values that can then be used as an argument in the BufferedImage.getRaster().setDataElements() method of BufferedImage to put pixel colours to a BufferedImage Object. The BufferedImage must be of type BufferedImage.TYPE_BYTE_INDEXED, with each pixel's colour being defined the by the index into the indexed colour mapping.
      Parameters:
      nCols - the number of columns in the array of pixel intensity values.
      nRows - the number of rows in the array of pixel intensity values.
      pixValues - an array of pixel intensity values to look up.
      offset - an offset (in pixels) into the array of pixValues at which to start the lookup.
      dataType - the PixelDataType data type of the pixel intensity values.
      bytePixel - the byte array that will contain the intensity values as mapped by the ColourMapping. If interpolation is false, then bytePixel should have the same length as pixValue. If interpolation is true, then bytePixel should be four times as long as pixValues.
      min - the pixel intensity that maps to the bottom (lowest value) of the ColourMapping.
      max - the pixel intensity that maps to the top (highest value) of the ColourMapping.
      inverted - true if the mapping of colours should be inverted.
      mask - if non-null, then this is used to mask pixels so that they appear the same colour as the background.
      interpolate - true if the image should be interpolated in the horizontal and vertical directions with an interpolation factor of two. Bi-linear interpolation is used.
      complexMode - the ComplexMode for complex images.
      Throws:
      IllegalArgumentException - if the colours cannot be looked up.

    • colourLookupRGBInterlaced

      public static void colourLookupRGBInterlaced(int nCols, int nRows, byte[] pixValues, int offset, int[] intPixel, short min, short max, boolean inverted, BitSet mask, boolean interpolate, byte alpha, boolean transparentBackground)
      Converts an array of pixel intensity values into the int values that can then be used as an argument in the BufferedImage.getRaster().setDataElements() method of BufferedImage to put pixel colours to a BufferedImage Object.

      If the alpha value is 255 (totally opaque) then the BufferedImage must be of type BufferedImage.TYPE_INT_RGB, with each pixel's colour being defined by the R,G,B values packed into each int in the array.

      If the alpha value is other than 255 (transparent) then the BufferedImage must be of type BufferedImage.TYPE_INT_ARGB, with each pixel's colour being defined by the alpha,R,G,B values packed into each int in the array.

      The brightness and contrast of the image may be adjusted by setting min and max. These would be set to 0 and 255 respectively to show the full colour range. If these are changed, the colours are remapped so that the colour at the min is remapped to zero gun value, and the colour at the max is remapped to the gun value 255.

      Parameters:
      nCols - the number of columns in the array of pixel intensity values.
      nRows - the number of rows in the array of pixel intensity values.
      pixValues - an array of pixel intensity values to look up.
      offset - an offset (in pixels) into the array of pixValues at which to start the lookup.
      intPixel - the int array that will contain the colour values. If interpolation is false, then intPixel should have the same length as pixValue. If interpolation is true, then bytePixel should be four times as long as pixValues.
      min - the colour intensity that maps to a gun value of zero.
      max - the colour intensity that maps to a gun value of 255.
      inverted - true if the mapping of colours should be inverted.
      mask - if non-null, then this is used to mask pixels so that they appear the same colour as the background.
      interpolate - true if the image should be interpolated in the horizontal and vertical directions with an interpolation factor of two. Bi-linear interpolation is used.
      alpha - the opacity value. 0 is totally transparent and 255 is totally opaque.
      transparentBackground - if true, then any black pixels will be set completely transparent.

    • colourLookupRGBByPlane

      public static void colourLookupRGBByPlane(int nCols, int nRows, byte[] pixValues, int offset, int[] intPixel, short min, short max, boolean inverted, BitSet mask, boolean interpolate, byte alpha, boolean transparentBackground)
      Converts an array of pixel intensity values into the int values that can then be used as an argument in the BufferedImage.getRaster().setDataElements() method of BufferedImage to put pixel colours to a BufferedImage Object.

      If the alpha value is 255 (totally opaque) then the BufferedImage must be of type BufferedImage.TYPE_INT_RGB, with each pixel's colour being defined by the R,G,B values packed into each int in the array.

      If the alpha value is other than 255 (transparent) then the BufferedImage must be of type BufferedImage.TYPE_INT_ARGB, with each pixel's colour being defined by the alpha,R,G,B values packed into each int in the array.

      The brightness and contrast of the image may be adjusted by setting min and max. These would be set to 0 and 255 respectively to show the full colour range. If these are changed, the colours are remapped so that the colour at the min is remapped to zero gun value, and the colour at the max is remapped to the gun value 255.

      Parameters:
      nCols - the number of columns in the array of pixel intensity values.
      nRows - the number of rows in the array of pixel intensity values.
      pixValues - an array of pixel intensity values to look up.
      offset - an offset (in pixels) into the array of pixValues at which to start the lookup.
      intPixel - the int array that will contain the colour values. If interpolation is false, then intPixel should have the same length as pixValue. If interpolation is true, then bytePixel should be four times as long as pixValues.
      min - the colour intensity that maps to a gun value of zero.
      max - the colour intensity that maps to a gun value of 255.
      inverted - true if the mapping of colours should be inverted.
      mask - if non-null, then this is used to mask pixels so that they appear the same colour as the background.
      interpolate - true if the image should be interpolated in the horizontal and vertical directions with an interpolation factor of two. Bi-linear interpolation is used.
      alpha - the opacity value. 0 is totally transparent and 255 is totally opaque.
      transparentBackground - if true, then any black pixels will be set completely transparent.

    • colourLookupColourPacked

      public static void colourLookupColourPacked(int nCols, int nRows, byte[] pixValues, int offset, int[] intPixel, short min, short max, boolean inverted, BitSet mask, boolean interpolate, byte alpha, boolean transparentBackground)
      Converts an array of pixel intensity values into the int values that can then be used as an argument in the BufferedImage.getRaster().setDataElements() method of BufferedImage to put pixel colours to a BufferedImage Object.

      If the alpha value is 255 (totally opaque) then the BufferedImage must be of type BufferedImage.TYPE_INT_RGB, with each pixel's colour being defined by the R,G,B values packed into each int in the array.

      If the alpha value is other than 255 (transparent) then the BufferedImage must be of type BufferedImage.TYPE_INT_ARGB, with each pixel's colour being defined by the alpha,R,G,B values packed into each int in the array.

      The brightness and contrast of the image may be adjusted by setting min and max. These would be set to 0 and 255 respectively to show the full colour range. If these are changed, the colours are remapped so that the colour at the min is remapped to zero gun value, and the colour at the max is remapped to the gun value 255.

      Parameters:
      nCols - the number of columns in the array of pixel intensity values.
      nRows - the number of rows in the array of pixel intensity values.
      pixValues - an array of pixel intensity values to look up.
      offset - an offset (in pixels) into the array of pixValues at which to start the lookup.
      intPixel - the int array that will contain the colour values. If interpolation is false, then intPixel should have the same length as pixValue. If interpolation is true, then bytePixel should be four times as long as pixValues.
      min - the colour intensity that maps to a gun value of zero.
      max - the colour intensity that maps to a gun value of 255.
      inverted - true if the mapping of colours should be inverted.
      mask - if non-null, then this is used to mask pixels so that they appear the same colour as the background.
      interpolate - true if the image should be interpolated in the horizontal and vertical directions with an interpolation factor of two. Bi-linear interpolation is used.
      alpha - the opacity value. 0 is totally transparent and 255 is totally opaque.
      transparentBackground - if true, then any black pixels will be set completely transparent.

    • getNSlots

      public int getNSlots()
      Returns the number of slots in this ColourMapping.
      Returns:
      the number of slots in this ColourMapping.

    • getColour

      public Color getColour(short slot)
      Returns the colour in a particular slot of the colour mapping.
      Parameters:
      slot - the slot number of the colour mapping.
      Returns:
      the Color at loction slot of the colour mapping.

    • isGreyScale

      public boolean isGreyScale()
      Returns true if this is a grey scale ColourMapping.
      Returns:
      true if, for all the slots in the ColourMapping, the red, green and blue components are all of equal intensity.

    • getIconHeight

      public int getIconHeight()
      Get the height of the Icon used to represent this ColourMapping.
      Specified by:
      getIconHeight in interface Icon
      Returns:
      the height of the icon.

    • getIconWidth

      public int getIconWidth()
      Get the width of the Icon used to represent this ColourMapping.
      Specified by:
      getIconWidth in interface Icon
      Returns:
      the width of the icon.

    • paintIcon

      public void paintIcon(Component c, Graphics g, int x, int y)
      Paints the Icon used to represent this ColourMapping.
      Specified by:
      paintIcon in interface Icon

    • getEntriesString

      public String getEntriesString()
      Returns a String showing either:
      • The [R,G,B] entries for this ColourMapping, or
      • If the ColourMapping is MONOCHROME1 or MONOCHROME2, the String "MONOCHROME1" or "MONOCHROME2". In the case of these two ColourMappings, the mapping between pixel presentation values and gun values is not fixed, but depends on the characteristics of the display screen and ambient lighting conditions, as set by the user and stored in the user preferences on a host-by-host basis.
      Returns:
      a String showing the [R,G,B] entries for this ColourMapping, in the form:
      {R1,G1,B1}{R2,G2,B2}...{RN,GN,BN}, or the name of one the two special ColourMappings MONOCHROME1 or MONOCHROME2.

    • toString

      public String toString()
      Returns a String describing this ColourMapping.
      Overrides:
      toString in class Object
      Returns:
      a String describing this ColourMapping.

    • clone

      public ColourMapping clone()
      Returns an exact copy of this ColourMapping.
      Overrides:
      clone in class Object
      Returns:
      a clone of this ColourMapping instance.

    • setDisplaySettings

      public static void setDisplaySettings(float minLuminance, float maxLuminance, float gamma) throws IllegalArgumentException, InvalidColourMappingException
      Set the display characteristics. This updates the ColourMappings MONOCHROME1 and MONOCHROME1 to reflect the new settings for display and ambient lighting characteristics.
      Parameters:
      minLuminance - the luminance level of the display for a digital driver level (DDL) of zero for the red, green and blue guns. This luminance includes the effects of any ambient light falling on the display.
      maxLuminance - the luminance level of the display for a digital driver level (DDL) of 255 for the red, green and blue guns. This luminance includes the effects of any ambient light falling on the display.
      gamma - the gamma characteristic for the display. The change in luminance of the display (from the minLuminance) is assumed to be proportional to the DDL raised to the power gamma.
      Throws:
      IllegalArgumentException - if any of the arguments is outside the credible range for displays.
      InvalidColourMappingException - if the ColourMappings can't be set.

    • savePreferences

      public static void savePreferences()
      Saves the display settings for the DICOM standard display in the user's preferences. The settings are saved on a per-host basis.

    • getMinLuminance

      public static float getMinLuminance()
      Returns the current minimum display luminance setting for a digital driver level (DDL) of zero.
      Returns:
      the current setting of the display luminance under ambient lighting conditions for a black portion of the image.

    • getMaxLuminance

      public static float getMaxLuminance()
      Returns the current maximmum display luminance setting for a digital driver level (DDL) of 255.
      Returns:
      the current setting of the display luminance under ambient lighting conditions for a white portion of the image.

    • getGamma

      public static float getGamma()
      Returns the current gamma value setting for the display. The luminance of the display is assumed to be preportional to the DDL raised to the power of gamma.
      Returns:
      the current setting of the display gamma value.

    • getBuiltInMappings

      public static List<ColourMapping> getBuiltInMappings()
      Returns a java.util.List&lt;ColourMapping&gt; of the built-in ColourMappings.
      Returns:
      a list of built-in ColourMappings.

    • getUserMappings

      public static List<ColourMapping> getUserMappings()
      Returns a java.util.List&lt;ColourMapping&gt; of the ColourMappings imported by the user and stored in the user preferences.
      Returns:
      a list of imported ColourMappings.

    • getAllColourMappings

      public static List<ColourMapping> getAllColourMappings()
      Returns a java.util.List&lt;ColourMapping&gt; of all ColourMappings, both built-in and imported by the user.
      Returns:
      a list of all ColourMappings known to the system.

    • getAllColourMapNames

      public static String getAllColourMapNames()
      Returns a list of all ColourMapping names, as a comma-separated list.
      Returns:
      a comma-separated list of all ColourMapping names known to the system.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • main

      public static void main(String[] args)
      Runs the self-test on this class.
      Parameters:
      args - the program arguments (ignored).