Class ColorModelFactory
ColorModel
objects built from a sequence of colors.- Since:
- 1.0
- Version:
- 1.3
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate final int[][]
The Alpha-Red-Green-Blue codes for all segments of the piecewise function.private static final WeakHashSet
<ColorModelPatch> Shared instances ofColorModel
s.private final int
The color model type.private final double
The minimum (inclusive) and maximum (exclusive) sample values.private final double
The minimum (inclusive) and maximum (exclusive) sample values.private final int
The number of bands (usually 1) used for the construction of a single instance of aColorModel
.private final int[]
In a color map defined by a piecewise function, indices where to store the first interpolated value in the color map.private static final Map
<ColorModelFactory, ColorModel> A pool of color models previously created bycreateColorModel()
.private static final Comparator
<ColorsForRange> Comparator for sorting ranges by their minimal value.static final Color
The fully transparent color.private final int
The visible band (usually 0) used for the construction of a single instance of aColorModel
. -
Constructor Summary
ConstructorsModifierConstructorDescriptionprivate
ColorModelFactory
(int dataType, int numBands, int visibleBand, ColorsForRange[] colors) Constructs a newColorModelFactory
. -
Method Summary
Modifier and TypeMethodDescriptionprivate ColorModel
Constructs the color model from thecodes
andARGB
data.static ColorModel
createColorScale
(int dataType, int numBands, int visibleBand, double lower, double upper, Color... colors) Returns a color model interpolated for the given range of values.static ColorModel
createGrayScale
(int dataType, int numComponents, int visibleBand, double minimum, double maximum) Creates a color model for opaque images storing pixels as real numbers.static ColorModel
createGrayScale
(SampleModel model, int visibleBand, NumberRange<?> range) Creates a color model for opaque images storing pixels using the given sample model.static IndexColorModel
createIndexColorModel
(int numBands, int visibleBand, int[] ARGB, boolean hasAlpha, int transparent) Returns a tolerant index color model for the specified ARGB codes.static ColorModel
createPiecewise
(int dataType, int numBands, int visibleBand, Map<NumberRange<?>, Color[]> colors) Returns a color model interpolated for the ranges in the given map entries.(package private) static ColorModel
createPiecewise
(int dataType, int numBands, int visibleBand, ColorsForRange[] colors) Returns a color model interpolated for the given ranges and colors.static ColorModel
createRGB
(int bitsPerSample, boolean packed, boolean hasAlpha) Creates a RGB color model.static ColorModel
createRGB
(SampleModel model) Creates a RGB color model for the given sample model.static Optional
<ColorModel> createSubset
(ColorModel cm, int[] bands) Creates a color model with only a subset of the bands of the given color model.boolean
Public as an implementation side-effect.static void
expand
(int[] colors, int[] ARGB, int lower, int upper) Copiescolors
intoARGB
array from indexlower
inclusive to indexupper
exclusive.static void
formatDescription
(ColorSpace cs, StringBuilder buffer) Appends a description of the given color space in the given buffer.static int
getBitCount
(int mapSize) Returns a bit count for anIndexColorModel
mappingmapSize
colors.private static int
getTransferType
(int mapSize) Returns a suggested type for anIndexColorModel
ofmapSize
colors.int
hashCode()
Public as an implementation side-effect.(package private) static boolean
isStandardRange
(int dataType, double minimum, double maximum) Returnstrue
if the given range of values is the standard range for the given data type.private static int
roundByte
(float value) Rounds a float value and clamps the result between 0 and 255 inclusive.toString()
Returns a string representation for debugging purposes.private static <T extends ColorModel>
Tunique
(T cm) Returns a unique instance of the given color model.
-
Field Details
-
TRANSPARENT
The fully transparent color. -
CACHE
Shared instances ofColorModel
s. Maintaining shared instance is not that much interesting for most kind of color models, exceptIndexColorModel
which can potentially be quite big. This class works for all color models because they were no technical reasons to restrict, but the real interest is to share index color models.- See Also:
-
PIECEWISES
A pool of color models previously created bycreateColorModel()
.Note: we use weak references instead of soft references because the intent is not to cache the values. The intent is to share existing instances in order to reduce memory usage. Rational:ColorModel
may consume a lot of memory. A 16 bits indexed color model can consume up to 256 kb. We do not want to retain such large objects longer than necessary. We want to share existing instances without preventing the garbage collector to collect them.createColorModel()
is reasonably fast if invoked only occasionally, so it is not worth consuming 256 kb for saving the few milliseconds requiring for building a new color model. Client code should retains their own reference to aColorModel
if they plan to reuse it often in a short period of time.
-
RANGE_COMPARATOR
Comparator for sorting ranges by their minimal value. -
dataType
private final int dataTypeThe color model type. One of the following types:DataBuffer.TYPE_BYTE
orDataBuffer.TYPE_USHORT
: will create aIndexColorModel
(unless grayscale).DataBuffer.TYPE_FLOAT
orDataBuffer.TYPE_DOUBLE
: will create aComponentColorModel
.DataBuffer.TYPE_INT
: should create aPackedColorModel
accordingRaster
javadoc (for compatibility withRaster.createPackedRaster(…)
), but we nevertheless createComponentColorModel
for the 1-banded sample model created byRasterFactory
.
-
numBands
private final int numBandsThe number of bands (usually 1) used for the construction of a single instance of aColorModel
. -
visibleBand
private final int visibleBandThe visible band (usually 0) used for the construction of a single instance of aColorModel
. -
minimum
private final double minimumThe minimum (inclusive) and maximum (exclusive) sample values. This is used only ifdataType
is notDataBuffer.TYPE_BYTE
orDataBuffer.TYPE_USHORT
. -
maximum
private final double maximumThe minimum (inclusive) and maximum (exclusive) sample values. This is used only ifdataType
is notDataBuffer.TYPE_BYTE
orDataBuffer.TYPE_USHORT
. -
pieceStarts
private final int[] pieceStartsIn a color map defined by a piecewise function, indices where to store the first interpolated value in the color map. The number of pieces (segments) ispieceStarts.length
. The last element of this array is the index after the end of the last piece. The indices are integers. Nevernull
but may be empty.Note: indices as unsigned short are not sufficient because in the worst case the last next index will be 65536, which would be converted to 0 as a short, causing several exceptions afterward. -
ARGB
private final int[][] ARGBThe Alpha-Red-Green-Blue codes for all segments of the piecewise function. This isnull
ifpieceStarts
is empty.
-
-
Constructor Details
-
ColorModelFactory
Constructs a newColorModelFactory
. This object will be used as a key in aMap
, so this is not really aColorModelFactory
but a kind of "ColorModelKey
" instead. However, since this constructor is private, user does not need to know that.- See Also:
-
-
Method Details
-
createColorModel
Constructs the color model from thecodes
andARGB
data. This method is invoked the first time the color model is created, or when the value in the cache has been discarded. -
hashCode
public int hashCode()Public as an implementation side-effect. -
equals
Public as an implementation side-effect. -
createPiecewise
public static ColorModel createPiecewise(int dataType, int numBands, int visibleBand, Map<NumberRange<?>, Color[]> colors) Returns a color model interpolated for the ranges in the given map entries. Returned instances ofColorModel
are shared among all callers in the running virtual machine.- Parameters:
dataType
- the color model type. One ofDataBuffer.TYPE_BYTE
,DataBuffer.TYPE_USHORT
,DataBuffer.TYPE_SHORT
,DataBuffer.TYPE_INT
,DataBuffer.TYPE_FLOAT
orDataBuffer.TYPE_DOUBLE
.numBands
- the number of bands for the color model (usually 1). The returned color model will render only thevisibleBand
and ignore the others, but the existence of allnumBands
will be at least tolerated. Supplemental bands, even invisible, are useful for processing.visibleBand
- the band to be made visible (usually 0). All other bands (if any) will be ignored.colors
- the colors to use for each range of sample values. The map may containnull
values, which means transparent.- Returns:
- a color model suitable for
RenderedImage
objects with values in the given ranges. - See Also:
-
createPiecewise
static ColorModel createPiecewise(int dataType, int numBands, int visibleBand, ColorsForRange[] colors) Returns a color model interpolated for the given ranges and colors. This method builds up the color model from each set of colors associated to ranges in the given entries. Returned instances ofColorModel
are shared among all callers in the running virtual machine.The given ranges are rounded to nearest integers and clamped to the range of 32 bits integer values. The associated arrays of colors do not need to have a length equals to
upper
−lower
; color interpolations will be applied as needed.- Parameters:
dataType
- the color model type. One ofDataBuffer.TYPE_BYTE
,DataBuffer.TYPE_USHORT
,DataBuffer.TYPE_SHORT
,DataBuffer.TYPE_INT
,DataBuffer.TYPE_FLOAT
orDataBuffer.TYPE_DOUBLE
.numBands
- the number of bands for the color model (usually 1). The returned color model will render only thevisibleBand
and ignore the others, but the existence of allnumBands
will be at least tolerated. Supplemental bands, even invisible, are useful for processing.visibleBand
- the band to be made visible (usually 0). All other bands, if any, will be ignored.colors
- the colors associated to ranges of sample values.- Returns:
- a color model suitable for
RenderedImage
objects with values in the given ranges.
-
createIndexColorModel
public static IndexColorModel createIndexColorModel(int numBands, int visibleBand, int[] ARGB, boolean hasAlpha, int transparent) Returns a tolerant index color model for the specified ARGB codes. This color model accepts image with the specified number of bands.This methods caches previously created instances using weak references, because index color model may be big (up to 256 kb).
- Parameters:
numBands
- the number of bands.visibleBand
- the band to display.ARGB
- an array of ARGB values.hasAlpha
- indicates whether alpha values are contained in theARGB
array.transparent
- the transparent pixel, or -1 for auto-detection.- Returns:
- An index color model for the specified array.
-
createColorScale
public static ColorModel createColorScale(int dataType, int numBands, int visibleBand, double lower, double upper, Color... colors) Returns a color model interpolated for the given range of values. This is a convenience method forcreatePiecewise(int, int, int, Map)
when the map contains only one element.- Parameters:
dataType
- the color model type.numBands
- the number of bands for the color model (usually 1).visibleBand
- the band to be made visible (usually 0). All other bands (if any) will be ignored.lower
- the minimum value, inclusive.upper
- the maximum value, exclusive.colors
- the colors to use for the range of sample values.- Returns:
- a color model suitable for
RenderedImage
objects with values in the given ranges.
-
createGrayScale
public static ColorModel createGrayScale(int dataType, int numComponents, int visibleBand, double minimum, double maximum) Creates a color model for opaque images storing pixels as real numbers. The color model can have an arbitrary number of bands, but in current implementation only one band is used.Warning: the use of this color model is very slow. It should be used only when no standard color model can be used.
- Parameters:
dataType
- the color model type as one ofDataBuffer.TYPE_*
constants.numComponents
- the number of components.visibleBand
- the band to use for computing colors.minimum
- the minimal sample value expected.maximum
- the maximal sample value expected.- Returns:
- the color model for the given range of values.
- See Also:
-
isStandardRange
static boolean isStandardRange(int dataType, double minimum, double maximum) Returnstrue
if the given range of values is the standard range for the given data type. In such case it may be possible to use a Java standard color model, which sometimes benefit from acceleration in Java2D rendering pipe.This method does not clamp the given values to the maximum range supported by the given type. For example, even if
TYPE_BYTE
cannot represent values outside the [0 … 255] range, we do not clamp the minimum and maximum values to that range because it would change the visual appearance (because of different color scale).- Parameters:
dataType
- one ofDataBuffer
constants.minimum
- the minimal sample value expected.maximum
- the maximal sample value expected.- Returns:
- whether the given minimum and maximum are the standard range for the given type.
-
createGrayScale
Creates a color model for opaque images storing pixels using the given sample model. The color model can have an arbitrary number of bands, but in current implementation only one band is used.Warning: the use of this color model may be very slow and the color stretching may not be a good fit. This method should be used only when no standard color model can be used. This is a last resort method.
- Parameters:
model
- the sample model for which to create a gray scale color model.visibleBand
- the band to use for computing colors.range
- the minimal and maximal sample value expected, ornull
if none.- Returns:
- the color model for the given range of values.
-
createRGB
Creates a RGB color model for the given sample model. The sample model shall use integer type and have 3 or 4 bands.- Parameters:
model
- the sample model for which to create a color model.- Returns:
- the color model.
-
createRGB
Creates a RGB color model. Thepacked
argument should betrue
for color model used withSinglePixelPackedSampleModel
, andfalse
for color model used withBandedSampleModel
.- Parameters:
bitsPerSample
- number of bits per sample, between 1 and 8 inclusive.packed
- whether sample values are packed in a single element.hasAlpha
- whether the color model should have an alpha channel.- Returns:
- the color model.
-
createSubset
Creates a color model with only a subset of the bands of the given color model. The returned color model is compatible with a subset sample model created with the same argument than thebands
argument given to this method. This method might not produce a result in following cases:- Input color model is null.
- Given color model is not assignable from the following types:
- Input color model is recognized, but we cannot infer a proper color interpretation for given number of bands.
PackedColorModel
andDirectColorModel
: they're not managed for now, because they're really designed for a "rigid" case where data buffer values are interpreted directly by the color model.- Parameters:
cm
- the color model, ornull
.bands
- the bands to select. Must neither be null nor empty.- Returns:
- the subset color model, or empty if input was null or if a subset cannot be deduced.
-
formatDescription
Appends a description of the given color space in the given buffer. This is used fortoString()
method implementations.- Parameters:
cs
- the color space to describe, ornull
.buffer
- where to append the description.
-
unique
Returns a unique instance of the given color model. This method is automatically invoked bycreate(…)
methods in this class.- Type Parameters:
T
- the type of the color model to share.- Parameters:
cm
- the color model for which to get a unique instance.- Returns:
- a unique (shared) instance of the given color model.
-
getTransferType
private static int getTransferType(int mapSize) Returns a suggested type for anIndexColorModel
ofmapSize
colors. This method returnsDataBuffer.TYPE_BYTE
orDataBuffer.TYPE_USHORT
.- Parameters:
mapSize
- the number of colors in the map.- Returns:
- the suggested transfer type.
-
getBitCount
public static int getBitCount(int mapSize) Returns a bit count for anIndexColorModel
mappingmapSize
colors. It is guaranteed that the following relation is hold:- Parameters:
mapSize
- the number of colors in the map.- Returns:
- the number of bits to use.
-
expand
public static void expand(int[] colors, int[] ARGB, int lower, int upper) Copiescolors
intoARGB
array from indexlower
inclusive to indexupper
exclusive. Ifupper-lower
is not equal to the length ofcolors
array, then colors will be interpolated. The givencolors
array must be initialized with zero values in thelower
…upper
range.- Parameters:
colors
- colors to copy into theARGB
array.ARGB
- array of integer to write ARGB values into.lower
- index (inclusive) of the first element ofARGB
to change.upper
- index (exclusive) of the last element ofARGB
to change.
-
roundByte
private static int roundByte(float value) Rounds a float value and clamps the result between 0 and 255 inclusive.- Parameters:
value
- the value to round.- Returns:
- the rounded and clamped value.
-
toString
Returns a string representation for debugging purposes.
-