Package org.apache.sis.internal.coverage.j2d

Class Colorizer

java.lang.Object
org.apache.sis.internal.coverage.j2d.Colorizer
public final class Colorizer extends Object
Helper classes for allowing an image to be colorized, by building an IndexColorModel if needed. Image created by this class are suitable for visualization purposes but generally not for computations. Usage:
  1. Create a new Colorizer instance.
  2. Invoke one of initialize(…) methods.
  3. Invoke createColorModel(int, int, int).
  4. Discards Colorizer; each instance should be used only once.
There is no 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:
  • ColorModelType
  • ColorModelFactory#createColorModel(int, int, int, Collection)

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private static final org.opengis.util.InternationalString
    COLOR_INDEX
    Names to use for the synthetic categories and sample dimensions created for visualization purposes.
    private final Function<Category,Color[]>
    colors
    The colors to use for each category.
    private NumberRange<?>
    defaultRange
    Default range of values to use if no explicitly specified by a Category.
    private ColorsForRange[]
    entries
    The colors to use for each range of values in the source image.
    static final Function<Category,Color[]>
    GRAYSCALE
    Applies a gray scale to quantitative category and transparent colors to qualitative categories.
    private static final int
    MAX_VALUE
    Maximal index value which can be used with a 8 bits IndexColorModel, inclusive.
    static final ColorModel
    NULL_COLOR_MODEL
    A color model constant set to null, used for identifying code that explicitly set the color model to null.
    private SampleDimension
    source
    The sample dimension for values before conversion, or null if unspecified.
    private SampleDimension
    target
    The sample dimension for values after conversion, or null if not yet computed.
    private static final org.opengis.util.InternationalString
    TRANSPARENT
    Names to use for the synthetic categories and sample dimensions created for visualization purposes.
    static final int
    TYPE_COMPACT
    The type resulting from sample values conversion applied by compactColorModel(int, int).
    private static final org.opengis.util.InternationalString
    VISUAL
    Names to use for the synthetic categories and sample dimensions created for visualization purposes.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Colorizer(Collection<Map.Entry<NumberRange<?>,Color[]>> colors)
    Creates a new colorizer which will apply colors on the given range of values in source image.
    Colorizer(Function<Category,Color[]> colors)
    Creates a new colorizer which will use the given function for determining the colors to apply.

  • Method Summary

    Modifier and Type
    Method
    Description
    private void
    checkInitializationStatus(boolean initialized)
    Verifies whether the entries value is defined.
    private void
    compact()
    Modifies the sample value ranges to make them fit in valid ranges for an IndexColorModel.
    ColorModel
    compactColorModel(int numBands, int visibleBand)
    Returns a color model with colors interpolated in the [0 … 255] range of values.
    ColorModel
    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
    getSampleToIndexValues()
    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)
    Returns true 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.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • NULL_COLOR_MODEL

      public static final ColorModel NULL_COLOR_MODEL
      A color model constant set to null, used for identifying code that explicitly set the color model to null. It may happen when no initialize(…) method can be applied.

    • TRANSPARENT

      private static final org.opengis.util.InternationalString TRANSPARENT
      Names 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, a colors 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_INDEX
      Names 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, a colors function could confuse synthetic categories with "real" categories with uninformative name, and consequently apply wrong colors.

    • VISUAL

      private static final org.opengis.util.InternationalString VISUAL
      Names 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, a colors function could confuse synthetic categories with "real" categories with uninformative name, and consequently apply wrong colors.

    • MAX_VALUE

      private static final int MAX_VALUE
      Maximal index value which can be used with a 8 bits IndexColorModel, inclusive. Sample values must be in that range for enabling the use of TYPE_COMPACT.
      See Also:

    • TYPE_COMPACT

      public static final int TYPE_COMPACT
      The type resulting from sample values conversion applied by compactColorModel(int, int). Current value is DataBuffer.TYPE_BYTE.
      See Also:

    • GRAYSCALE

      public static final Function<Category,Color[]> GRAYSCALE
      Applies a gray scale to quantitative category and transparent colors to qualitative categories. This is a possible argument for the Colorizer(Function) constructor.

    • colors

      private final Function<Category,Color[]> colors
      The colors to use for each category. Never null. The function may return null, which means transparent.

    • entries

      private ColorsForRange[] 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

      private SampleDimension source
      The sample dimension for values before conversion, or null 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

      private SampleDimension target
      The sample dimension for values after conversion, or null if not yet computed. May be the same than source or source.forConvertedValues(true) if one of those values is suitable, or a new sample dimension created by compact().

      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

      private NumberRange<?> defaultRange
      Default range of values to use if no explicitly specified by a Category.

  • Constructor Details

    • Colorizer

      public Colorizer(Collection<Map.Entry<NumberRange<?>,Color[]>> colors)
      Creates a new colorizer which will apply colors on the given range of values in source image. The Colorizer is considered initialized after this constructor; callers shall not invoke an initialize(…) method.
      Parameters:
      colors - the colors to use for each range of values in source image. A null entry value means transparent.

    • Colorizer

      public Colorizer(Function<Category,Color[]> colors)
      Creates a new colorizer which will use the given function for determining the colors to apply. Callers need to invoke an initialize(…) method after this constructor.
      Parameters:
      colors - the colors to use for each category, or null for default. The function may return null, which means transparent.

  • Method Details

    • checkInitializationStatus

      private void checkInitializationStatus(boolean initialized)
      Verifies whether the entries value is defined.
      Parameters:
      initialized - the expected initialization state.

    • isAlreadyScaled

      private static boolean isAlreadyScaled(NumberRange<?> range)
      Returns true if the given range is already the [0 … 255] range.

    • initialize

      public boolean initialize(SampleModel model, SampleDimension source)
      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 to colors.apply(category) where colors is the function specified at construction time.
      Parameters:
      model - the sample model used with the data, or null if unknown.
      source - description of range of values in the source image, or null.
      Returns:
      true on success, or false if no range of values has been found.
      Throws:
      IllegalStateException - if a sample dimension is already defined on this colorizer.

    • initialize

      public boolean initialize(SampleModel source, int band)
      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, or null.
      band - raster band to be colored.
      Returns:
      true on success, or false if no range of values has been found.
      Throws:
      IllegalStateException - if a sample dimension is already defined on this colorizer.

    • initialize

      public boolean initialize(ColorModel source)
      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 this Colorizer); 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, or null.
      Returns:
      true on success, or false 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 no Category 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

      public void rescaleMainRange(ColorModel original)
      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, or null if none.
      Throws:
      IllegalStateException - if initialize(…) has not been invoked.

    • compact

      private void compact()
      Modifies the sample value ranges to make them fit in valid ranges for an IndexColorModel. The SampleDimension.getSampleRange() is constrained to range [0 … 255] inclusive. The SampleDimension.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 the entries array. For each ColorsForRange instance, the ColorsForRange.sampleRange range is replaced by range of indexed colors. In addition entries elements may be reordered.

      If has been built from a sample dimension, that SampleDimension is specified in the source field. This is used only for providing a better name to the sample dimension.

    • createColorModel

      public ColorModel createColorModel(int dataType, int numBands, int visibleBand)
      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 of ColorModel are shared among all callers in the running virtual machine.
      Parameters:
      dataType - the color model type. One of DataBuffer.TYPE_BYTE, DataBuffer.TYPE_USHORT, DataBuffer.TYPE_SHORT, DataBuffer.TYPE_INT, DataBuffer.TYPE_FLOAT or DataBuffer.TYPE_DOUBLE.
      numBands - the number of bands for the color model (usually 1). The returned color model will render only the visibleBand and ignore the others, but the existence of all numBands 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

      public ColorModel compactColorModel(int numBands, int visibleBand)
      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 by getSampleToIndexValues(). Images using this color model shall use a DataBuffer of type TYPE_COMPACT.
      Parameters:
      numBands - the number of bands for the color model (usually 1). The returned color model will render only the visibleBand and ignore the others, but the existence of all numBands 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.NoninvertibleTransformException
      Returns 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: