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
Author:
Martin Desruisseaux (Geomatys)
See Also:
  • ColorModelType
  • invalid reference 
    ColorModelFactory#createColorModel(int, int, int, Collection)

  • 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.

    • 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.

  • 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

    • 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.

    • 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.