Class Colorizer
IndexColorModel
if needed.
Image created by this class are suitable for visualization purposes but generally not for computations.
Usage:
- Create a new
Colorizer
instance. - Invoke one of
initialize(…)
methods. - Invoke
createColorModel(int, int, int)
. - Discards
Colorizer
; each instance should be used only once.
initialize(Raster)
or initialize(RenderedImage)
method because if those methods
were present, users may expect them to iterate over sample values for finding minimum and maximum values.
We do not perform such iteration because they are potentially costly and give unstable results:
the resulting color model varies from image to image, which is confusing when many images exist
for the same product at different times or at different depths.- Since:
- 1.1
- Version:
- 1.2
- See Also:
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final org.opengis.util.InternationalString
Names to use for the synthetic categories and sample dimensions created for visualization purposes.The colors to use for each category.private NumberRange
<?> Default range of values to use if no explicitly specified by aCategory
.private ColorsForRange[]
The colors to use for each range of values in the source image.Applies a gray scale to quantitative category and transparent colors to qualitative categories.private static final int
Maximal index value which can be used with a 8 bitsIndexColorModel
, inclusive.static final ColorModel
A color model constant set tonull
, used for identifying code that explicitly set the color model tonull
.private SampleDimension
The sample dimension for values before conversion, ornull
if unspecified.private SampleDimension
The sample dimension for values after conversion, ornull
if not yet computed.private static final org.opengis.util.InternationalString
Names to use for the synthetic categories and sample dimensions created for visualization purposes.static final int
The type resulting from sample values conversion applied bycompactColorModel(int, int)
.private static final org.opengis.util.InternationalString
Names to use for the synthetic categories and sample dimensions created for visualization purposes. -
Constructor Summary
ConstructorsConstructorDescriptionColorizer
(Collection<Map.Entry<NumberRange<?>, Color[]>> colors) Creates a new colorizer which will apply colors on the given range of values in source image.Creates a new colorizer which will use the given function for determining the colors to apply. -
Method Summary
Modifier and TypeMethodDescriptionprivate void
checkInitializationStatus
(boolean initialized) Verifies whether theentries
value is defined.private void
compact()
Modifies the sample value ranges to make them fit in valid ranges for anIndexColorModel
.compactColorModel
(int numBands, int visibleBand) Returns a color model with colors interpolated in the [0 … 255] range of values.createColorModel
(int dataType, int numBands, int visibleBand) Returns a color model with colors interpolated in the ranges of values determined by constructors.org.opengis.referencing.operation.MathTransform1D
Returns the conversion from sample values in the source image to sample values in the recolored image.private static org.opengis.referencing.operation.MathTransform1D
identity()
Returns the identity transform.void
initialize
(double minimum, double maximum) Applies colors on the given range of values.boolean
initialize
(ColorModel source) Uses the given color model for mapping range of values to new colors.boolean
initialize
(SampleModel source, int band) Applies colors on the range of values of a raster using given sample model.boolean
initialize
(SampleModel model, SampleDimension source) Uses the given sample dimension for mapping range of values to colors.private static boolean
isAlreadyScaled
(NumberRange<?> range) Returnstrue
if the given range is already the [0 … 255] range.void
rescaleMainRange
(ColorModel original) Potentially rescales the range of values of the main category for the given color model.
-
Field Details
-
NULL_COLOR_MODEL
A color model constant set tonull
, used for identifying code that explicitly set the color model tonull
. It may happen when noinitialize(…)
method can be applied. -
TRANSPARENT
private static final org.opengis.util.InternationalString TRANSPARENTNames to use for the synthetic categories and sample dimensions created for visualization purposes. Transparent pixel is usually 0 and opaque pixels are in the range 1 to 255 inclusive.For safety, we use names that are different than the default "No data" and "Data" names assigned by
SampleDimension.Builder
. The "[No] data" default names are often used by formats that are poor in metadata, for example ASCII Grid. If we were using the same names, acolors
function could confuse synthetic categories with "real" categories with uninformative name, and consequently apply wrong colors. -
COLOR_INDEX
private static final org.opengis.util.InternationalString COLOR_INDEXNames to use for the synthetic categories and sample dimensions created for visualization purposes. Transparent pixel is usually 0 and opaque pixels are in the range 1 to 255 inclusive.For safety, we use names that are different than the default "No data" and "Data" names assigned by
SampleDimension.Builder
. The "[No] data" default names are often used by formats that are poor in metadata, for example ASCII Grid. If we were using the same names, acolors
function could confuse synthetic categories with "real" categories with uninformative name, and consequently apply wrong colors. -
VISUAL
private static final org.opengis.util.InternationalString VISUALNames to use for the synthetic categories and sample dimensions created for visualization purposes. Transparent pixel is usually 0 and opaque pixels are in the range 1 to 255 inclusive.For safety, we use names that are different than the default "No data" and "Data" names assigned by
SampleDimension.Builder
. The "[No] data" default names are often used by formats that are poor in metadata, for example ASCII Grid. If we were using the same names, acolors
function could confuse synthetic categories with "real" categories with uninformative name, and consequently apply wrong colors. -
MAX_VALUE
private static final int MAX_VALUEMaximal index value which can be used with a 8 bitsIndexColorModel
, inclusive. Sample values must be in that range for enabling the use ofTYPE_COMPACT
.- See Also:
-
TYPE_COMPACT
public static final int TYPE_COMPACTThe type resulting from sample values conversion applied bycompactColorModel(int, int)
. Current value isDataBuffer.TYPE_BYTE
.- See Also:
-
GRAYSCALE
Applies a gray scale to quantitative category and transparent colors to qualitative categories. This is a possible argument for theColorizer(Function)
constructor. -
colors
The colors to use for each category. Nevernull
. The function may returnnull
, which means transparent. -
entries
The colors to use for each range of values in the source image. Entries will be sorted and modified in place. The array may be null if unspecified, but shall not contain null element. -
source
The sample dimension for values before conversion, ornull
if unspecified. This object describes the range of values found in source image. They are not necessarily the range of values in the colorized image. -
target
The sample dimension for values after conversion, ornull
if not yet computed. May be the same thansource
orsource.forConvertedValues(true)
if one of those values is suitable, or a new sample dimension created bycompact()
.This sample dimension should not be returned to the user because it may not contain meaningful values. For example, it may contain an "artificial" transfer function for computing a
MathTransform1D
from source range to the [0 … 255] value range. -
defaultRange
Default range of values to use if no explicitly specified by aCategory
.
-
-
Constructor Details
-
Colorizer
Creates a new colorizer which will apply colors on the given range of values in source image. TheColorizer
is considered initialized after this constructor; callers shall not invoke aninitialize(…)
method.- Parameters:
colors
- the colors to use for each range of values in source image. Anull
entry value means transparent.
-
Colorizer
Creates a new colorizer which will use the given function for determining the colors to apply. Callers need to invoke aninitialize(…)
method after this constructor.- Parameters:
colors
- the colors to use for each category, ornull
for default. The function may returnnull
, which means transparent.
-
-
Method Details
-
checkInitializationStatus
private void checkInitializationStatus(boolean initialized) Verifies whether theentries
value is defined.- Parameters:
initialized
- the expected initialization state.
-
isAlreadyScaled
Returnstrue
if the given range is already the [0 … 255] range. -
initialize
Uses the given sample dimension for mapping range of values to colors. For each category in the sample dimension, colors will be determined by a call tocolors.apply(category)
wherecolors
is the function specified at construction time.- Parameters:
model
- the sample model used with the data, ornull
if unknown.source
- description of range of values in the source image, ornull
.- Returns:
true
on success, orfalse
if no range of values has been found.- Throws:
IllegalStateException
- if a sample dimension is already defined on this colorizer.
-
initialize
Applies colors on the range of values of a raster using given sample model. The 0 index will be reserved for NaN value, and indices in the [1 … 255] range will be mapped to the range of sample values that can be stored in the specified band.- Parameters:
source
- sample model of raster to be colored, ornull
.band
- raster band to be colored.- Returns:
true
on success, orfalse
if no range of values has been found.- Throws:
IllegalStateException
- if a sample dimension is already defined on this colorizer.
-
initialize
Uses the given color model for mapping range of values to new colors. The colors in the given color model are ignored (because they will be replaced by colors specified by thisColorizer
); only the range of values will be fetched, if such range exists.- Parameters:
source
- the color model from which to get a range of values, ornull
.- Returns:
true
on success, orfalse
if no range of values has been found.- Throws:
IllegalStateException
- if a sample dimension is already defined on this colorizer.
-
initialize
public void initialize(double minimum, double maximum) Applies colors on the given range of values. The 0 index will be reserved for NaN value, and indices in the [1 … 255] will be mapped to the given range.This method is typically used as a last resort fallback when all other
initialize(…)
methods failed or cannot be applied. This method assumes that noCategory
information is available.- Parameters:
minimum
- minimum value, inclusive.maximum
- maximum value, inclusive.- Throws:
IllegalStateException
- if a sample dimension is already defined on this colorizer.
-
rescaleMainRange
Potentially rescales the range of values of the main category for the given color model. This method can be invoked when the color model may use a range of values different than the range specified by categories. It may happen if the color ramp associated to the quantitative category has been stretched dynamically using a "recolor" operation. We want to preserve that user customization, but we have no explicit information about which category to modify. This method does an heuristic choice based on the category having the largest intersection with the color model value range.An
initialize(…)
method must have been invoked successfully before this method can be invoked.- Parameters:
original
- original color model of image for which a new color map is built, ornull
if none.- Throws:
IllegalStateException
- ifinitialize(…)
has not been invoked.
-
compact
private void compact()Modifies the sample value ranges to make them fit in valid ranges for anIndexColorModel
. TheSampleDimension.getSampleRange()
is constrained to range [0 … 255] inclusive. TheSampleDimension.getTransferFunction()
returns the conversion from original ranges to ranges of pixel values in the colorized image.There is two outputs: the
target
sample dimension, and modifications done in-place in theentries
array. For eachColorsForRange
instance, theColorsForRange.sampleRange
range is replaced by range of indexed colors. In additionentries
elements may be reordered.If has been built from a sample dimension, that
SampleDimension
is specified in thesource
field. This is used only for providing a better name to the sample dimension. -
createColorModel
Returns a color model with colors interpolated in the ranges of values determined by constructors. This method builds up the color model from each set of colors associated to ranges in the given array. 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.- Returns:
- a color model suitable for
RenderedImage
objects with values in the given ranges.
-
compactColorModel
Returns a color model with colors interpolated in the [0 … 255] range of values. Conversions from range specified at construction time to the [0 … 255] range is given bygetSampleToIndexValues()
. Images using this color model shall use aDataBuffer
of typeTYPE_COMPACT
.- Parameters:
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.- Returns:
- a color model suitable for
RenderedImage
objects with values in the given ranges.
-
getSampleToIndexValues
public org.opengis.referencing.operation.MathTransform1D getSampleToIndexValues() throws org.opengis.referencing.operation.NoninvertibleTransformExceptionReturns the conversion from sample values in the source image to sample values in the recolored image.- Returns:
- conversion to sample values in recolored image.
- Throws:
org.opengis.referencing.operation.NoninvertibleTransformException
- if the conversion cannot be created.
-
identity
private static org.opengis.referencing.operation.MathTransform1D identity()Returns the identity transform.- See Also:
-