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

Class ColorModelFactory

java.lang.Object
org.apache.sis.internal.coverage.j2d.ColorModelFactory
public final class ColorModelFactory extends Object
A factory for ColorModel objects built from a sequence of colors.
Since:
1.0
Version:
1.3

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private final int[][]
    ARGB
    The Alpha-Red-Green-Blue codes for all segments of the piecewise function.
    private static final WeakHashSet<ColorModelPatch>
    CACHE
    Shared instances of ColorModels.
    private final int
    dataType
    The color model type.
    private final double
    maximum
    The minimum (inclusive) and maximum (exclusive) sample values.
    private final double
    minimum
    The minimum (inclusive) and maximum (exclusive) sample values.
    private final int
    numBands
    The number of bands (usually 1) used for the construction of a single instance of a ColorModel.
    private final int[]
    pieceStarts
    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>
    PIECEWISES
    A pool of color models previously created by createColorModel().
    private static final Comparator<ColorsForRange>
    RANGE_COMPARATOR
    Comparator for sorting ranges by their minimal value.
    static final Color
    TRANSPARENT
    The fully transparent color.
    private final int
    visibleBand
    The visible band (usually 0) used for the construction of a single instance of a ColorModel.

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    private
    ColorModelFactory(int dataType, int numBands, int visibleBand, ColorsForRange[] colors)
    Constructs a new ColorModelFactory.

  • Method Summary

    Modifier and Type
    Method
    Description
    private ColorModel
    createColorModel()
    Constructs the color model from the codes and ARGB 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
    equals(Object other)
    Public as an implementation side-effect.
    static void
    expand(int[] colors, int[] ARGB, int lower, int upper)
    Copies colors into ARGB array from index lower inclusive to index upper 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 an IndexColorModel mapping mapSize colors.
    private static int
    getTransferType(int mapSize)
    Returns a suggested type for an IndexColorModel of mapSize colors.
    int
    hashCode()
    Public as an implementation side-effect.
    (package private) static boolean
    isStandardRange(int dataType, double minimum, double maximum)
    Returns true 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.
    String
    toString()
    Returns a string representation for debugging purposes.
    private static <T extends ColorModel>
    T
    unique(T cm)
    Returns a unique instance of the given color model.

    Methods inherited from class java.lang.Object

    clone, finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • TRANSPARENT

      public static final Color TRANSPARENT
      The fully transparent color.

    • CACHE

      private static final WeakHashSet<ColorModelPatch> CACHE
      Shared instances of ColorModels. Maintaining shared instance is not that much interesting for most kind of color models, except IndexColorModel 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

      private static final Map<ColorModelFactory,ColorModel> PIECEWISES
      A pool of color models previously created by createColorModel().
      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 a ColorModel if they plan to reuse it often in a short period of time.

    • RANGE_COMPARATOR

      private static final Comparator<ColorsForRange> RANGE_COMPARATOR
      Comparator for sorting ranges by their minimal value.

    • dataType

      private final int dataType
      The color model type. One of the following types:

    • numBands

      private final int numBands
      The number of bands (usually 1) used for the construction of a single instance of a ColorModel.

    • visibleBand

      private final int visibleBand
      The visible band (usually 0) used for the construction of a single instance of a ColorModel.

    • minimum

      private final double minimum
      The minimum (inclusive) and maximum (exclusive) sample values. This is used only if dataType is not DataBuffer.TYPE_BYTE or DataBuffer.TYPE_USHORT.

    • maximum

      private final double maximum
      The minimum (inclusive) and maximum (exclusive) sample values. This is used only if dataType is not DataBuffer.TYPE_BYTE or DataBuffer.TYPE_USHORT.

    • pieceStarts

      private final int[] pieceStarts
      In 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) is pieceStarts.length. The last element of this array is the index after the end of the last piece. The indices are integers. Never null 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[][] ARGB
      The Alpha-Red-Green-Blue codes for all segments of the piecewise function. This is null if pieceStarts is empty.

  • Constructor Details

    • ColorModelFactory

      private ColorModelFactory(int dataType, int numBands, int visibleBand, ColorsForRange[] colors)
      Constructs a new ColorModelFactory. This object will be used as a key in a Map, so this is not really a ColorModelFactory but a kind of "ColorModelKey" instead. However, since this constructor is private, user does not need to know that.
      See Also:

  • Method Details

    • createColorModel

      private ColorModel createColorModel()
      Constructs the color model from the codes and ARGB 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.
      Overrides:
      hashCode in class Object
      Returns:
      a hash code.

    • equals

      public boolean equals(Object other)
      Public as an implementation side-effect.
      Overrides:
      equals in class Object
      Parameters:
      other - the other object to compare for equality.
      Returns:
      whether the two objects are equal.

    • 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 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.
      colors - the colors to use for each range of sample values. The map may contain null 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 of ColorModel 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 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.
      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 the ARGB 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 for createPiecewise(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 of DataBuffer.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)
      Returns true 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 of DataBuffer 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

      public static ColorModel createGrayScale(SampleModel model, int visibleBand, NumberRange<?> range)
      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, or null if none.
      Returns:
      the color model for the given range of values.

    • createRGB

      public static ColorModel createRGB(SampleModel model)
      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

      public static ColorModel createRGB(int bitsPerSample, boolean packed, boolean hasAlpha)
      Creates a RGB color model. The packed argument should be true for color model used with SinglePixelPackedSampleModel, and false for color model used with BandedSampleModel.
      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

      public static Optional<ColorModel> createSubset(ColorModel cm, int[] bands)
      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 the bands argument given to this method. This method might not produce a result in following cases: Note about PackedColorModel and DirectColorModel: 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, or null.
      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

      @Debug public static void formatDescription(ColorSpace cs, StringBuilder buffer)
      Appends a description of the given color space in the given buffer. This is used for toString() method implementations.
      Parameters:
      cs - the color space to describe, or null.
      buffer - where to append the description.

    • unique

      private static <T extends ColorModel> T unique(T cm)
      Returns a unique instance of the given color model. This method is automatically invoked by create(…) 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 an IndexColorModel of mapSize colors. This method returns DataBuffer.TYPE_BYTE or DataBuffer.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 an IndexColorModel mapping mapSize 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)
      Copies colors into ARGB array from index lower inclusive to index upper exclusive. If upper-lower is not equal to the length of colors array, then colors will be interpolated. The given colors array must be initialized with zero values in the lower … upper range.
      Parameters:
      colors - colors to copy into the ARGB array.
      ARGB - array of integer to write ARGB values into.
      lower - index (inclusive) of the first element of ARGB to change.
      upper - index (exclusive) of the last element of ARGB 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

      public String toString()
      Returns a string representation for debugging purposes.
      Overrides:
      toString in class Object
      Returns:
      a string representation of this color factory.