com.xinapse.multisliceimage
Class ColourMapping

java.lang.Object
  com.xinapse.multisliceimage.ColourMapping

All Implemented Interfaces:

java.lang.Cloneable, javax.swing.Icon

Direct Known Subclasses:

ANZColourMapping

public class ColourMapping
extends java.lang.Object
implements javax.swing.Icon, java.lang.Cloneable

The ColourMapping class represents a mapping from pixel presentation values (PPVs) to colours that are displayed as an image.

The class has a number of built-in colour mappings, and contains the methods to create custom colour mappings. 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 Summary

static ColourMapping	BLUE The ColourMapping representing a blue intensity scale.
java.awt.image.IndexColorModel	cm The IndexColorModel used to contain the mapping.
static ColourMapping	COOL The Cool ColourMapping scale.
static ColourMapping	CYAN The ColourMapping representing a cyan intensity scale.
static float	DEFAULT_GAMMA The default gamma value of the computer display.
static 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.
static 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.
static ColourMapping	GREEN The ColourMapping representing a green intensity scale.
static ColourMapping	HOBS The ColourMapping representing a hot body (black to white via red) intensity scale.
static ColourMapping	MAGENTA The ColourMapping representing a magenta intensity scale.
static float	MAX_GAMMA The maximum display gamma value that is allowed.
static float	MAX_LUMINANCE The maximum value of display luminance (for a DDL of 255) that is allowed (including ambient light).
static float	MIN_GAMMA The minimum display gamma value that is allowed.
static float	MIN_LUMINANCE The minimum value of display luminance (for a DDL of zero) that is allowed (including ambient light).
static ColourMapping	MONOCHROME1 The ColourMapping representing a grey (white to black) intensity scale.
static ColourMapping	MONOCHROME2 The ColourMapping representing a grey (black to white) intensity scale.
static ColourMapping	RBOW1 The ColourMapping representing a rainbow of colours intensity scale.
static ColourMapping	RBOW2 The ColourMapping representing an alternative rainbow of colours intensity scale.
static ColourMapping	RED The ColourMapping representing a red intensity scale.
static ColourMapping	STEP The ColourMapping representing a step change in intensity scale.
static ColourMapping	YELLOW The ColourMapping representing a yellow intensity scale.

Constructor Summary

ColourMapping(byte[] red, byte[] green, byte[] blue)
Creates a new ColourMapping object from a set of red, green and blue gun values.

ColourMapping(short nSlots)
Creates an empty ColourMapping with the specified number of slots in the map.

Method Summary

java.lang.Object	clone() Returns an exact copy of this ColourMapping.
void	colourLookup(int nCols, int nRows, java.lang.Object pixValues, int offset, PixelDataType dataType, byte[] bytePixel, double min, double max, boolean inverted, boolean[] mask, boolean interpolate, ComplexMode complexMode) Converts an array of pixel intensity values into the byte values that can then be used as an argument in the getRaster().setDataElements() method of BufferedImage to put pixel colours to a BufferedImage Object.
static void	colourLookupColourPacked(int nCols, int nRows, byte[] pixValues, int offset, int[] intPixel, short min, short max, boolean inverted, boolean[] 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 getRaster().setDataElements() method of BufferedImage to put pixel colours to a BufferedImage Object.
static void	colourLookupRGBByPlane(int nCols, int nRows, byte[] pixValues, int offset, int[] intPixel, short min, short max, boolean inverted, boolean[] 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 getRaster().setDataElements() method of BufferedImage to put pixel colours to a BufferedImage Object.
static void	colourLookupRGBInterlaced(int nCols, int nRows, byte[] pixValues, int offset, int[] intPixel, short min, short max, boolean inverted, boolean[] 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 getRaster().setDataElements() method of BufferedImage to put pixel colours to a BufferedImage Object.
static ColourMapping	get(java.lang.String name) Returns one of the "built-in" ColourMappings, selected according to its name.
java.awt.Color	getColour(short slot) Returns the colour in a particular slot of the colour mapping.
java.lang.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".
static float	getGamma() Returns the current gamma value setting for the display.
int	getIconHeight() Get the height of the Icon used to represent this ColourMapping.
int	getIconWidth() Get the width of the Icon used to represent this ColourMapping.
static ColourMapping	getInstance(java.lang.String entriesString) Creates a new ColourMapping object from a String representation of the ColourMapping name, or the list of entries in the ColourMapping.
static ColourMapping[]	getKnownColourMappings() Returns an array of known built-in ColorMappings.
static float	getMaxLuminance() Returns the current maximmum display luminance setting for a digital driver level (DDL) of 255.
static float	getMinLuminance() Returns the current minimum display luminance setting for a digital driver level (DDL) of zero.
int	getNSlots() Returns the number of slots in this ColourMapping.
boolean	isGreyScale() Returns true if this is a grey scale ColourMapping.
ColourMapping	makeTransparent(byte alpha, boolean transparentBackground) Add transparency (an alpha channel) to an existing ColourMapping.
void	paintIcon(java.awt.Component c, java.awt.Graphics g, int x, int y) Paints the Icon used to represent this ColourMapping.
static void	savePreferences() Saves the display settings for the DICOM standard display in the user's preferences.
static void	setDisplaySettings(float minLuminance, float maxLuminance, float gamma) Set the display characteristics.
void	setRGB(int[] red, int[] green, int[] blue) Sets the R,G,B components of every element of the ColourMapping.
java.lang.String	toString() Returns a String describing this ColourMapping.

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

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:

Constant Field Values

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:

Constant Field Values

MIN_GAMMA

public static final float MIN_GAMMA

The minimum display gamma value that is allowed.

See Also:

Constant Field Values

MAX_GAMMA

public static final float MAX_GAMMA

The maximum display gamma value that is allowed.

See Also:

Constant Field Values

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:

Constant Field Values

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:

Constant Field Values

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:

Constant Field Values

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.

COOL

public static final ColourMapping COOL

The Cool ColourMapping 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 java.awt.image.IndexColorModel cm

The IndexColorModel used to contain the mapping.

Constructor Detail

ColourMapping

public ColourMapping(short nSlots)

Creates an empty ColourMapping with the specified number of slots in the map.

Parameters:

nSlots - the number of slots in the ColourMapping.

ColourMapping

public ColourMapping(byte[] red,
                     byte[] green,
                     byte[] blue)
              throws InvalidColourMappingException

Creates a new ColourMapping object from a set of red, green and blue gun values.

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.

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.

Method Detail

getInstance

public static ColourMapping getInstance(java.lang.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 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

Throws:

InvalidColourMappingException - if the entries in the ColourMapping cannot be parsed from the entriesString.

get

public static ColourMapping get(java.lang.String name)
                         throws com.xinapse.util.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.

Throws:

com.xinapse.util.InvalidArgumentException - if the supplied name does not match any of the names of the built-in mappings.

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.

colourLookup

public void colourLookup(int nCols,
                         int nRows,
                         java.lang.Object pixValues,
                         int offset,
                         PixelDataType dataType,
                         byte[] bytePixel,
                         double min,
                         double max,
                         boolean inverted,
                         boolean[] mask,
                         boolean interpolate,
                         ComplexMode complexMode)
                  throws java.lang.IllegalArgumentException

Converts an array of pixel intensity values into the byte values that can then be used as an argument in the getRaster().setDataElements() method of BufferedImage to put pixel colours to a BufferedImage Object. The BufferedImage must be of type java.awt.image.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.

Throws:

java.lang.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,
                                             boolean[] 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 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 java.awt.image.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 java.awt.image.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,
                                          boolean[] 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 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 java.awt.image.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 java.awt.image.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,
                                            boolean[] 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 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 java.awt.image.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 java.awt.image.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.

setRGB

public void setRGB(int[] red,
                   int[] green,
                   int[] blue)
            throws InvalidColourMappingException

Sets the R,G,B components of every element of the ColourMapping.

Parameters:

red - an array of red gun values.

green - an array of green gun values.

blue - an array of blue gun values.

Throws:

InvalidColourMappingException - if the length of the arrays containing R,G,B values does not match the number of slots in the ColourMapping, or if any of the gun values is ouside the range [0..255].

getNSlots

public int getNSlots()

Returns the number of slots in this ColourMapping.

Returns:

the number of slots in this ColourMapping.

getColour

public java.awt.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 javax.swing.Icon

getIconWidth

public int getIconWidth()

Get the width of the Icon used to represent this ColourMapping.

Specified by:

getIconWidth in interface javax.swing.Icon

paintIcon

public void paintIcon(java.awt.Component c,
                      java.awt.Graphics g,
                      int x,
                      int y)

Paints the Icon used to represent this ColourMapping.

Specified by:

paintIcon in interface javax.swing.Icon

getKnownColourMappings

public static ColourMapping[] getKnownColourMappings()

Returns an array of known built-in ColorMappings.

Returns:

an array of known ColorMapping Objects.

getEntriesString

public java.lang.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 java.lang.String toString()

Returns a String describing this ColourMapping.

Overrides:

toString in class java.lang.Object

Returns:

a String describing this ColourMapping.

clone

public java.lang.Object clone()

Returns an exact copy of this ColourMapping.

Overrides:

clone in class java.lang.Object

Returns:

a clone of this ColourMapping instance.

setDisplaySettings

public static void setDisplaySettings(float minLuminance,
                                      float maxLuminance,
                                      float gamma)
                               throws java.lang.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:

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