Module org.apache.sis.feature
Package org.apache.sis.image

Interface Colorizer

All Superinterfaces:
Function<Colorizer​.Target,Optional<Color­Model>>
public interface Colorizer extends Function<Colorizer.Target,Optional<ColorModel>>
Colorization algorithm to apply for colorizing a computed image. The apply(Target) method is invoked when Image­Processor needs a new color model for the computation result. The Colorizer​.Target argument contains information about the image to colorize, in particular the Sample­Model of the computed image. The colorization result is optional, i.e. the apply(Target) method may return an empty value if it does not support the target. In the latter case the caller will fallback on a default color model, typically a grayscale.

Constants or static methods in this interface provide colorizers for common cases. For example ARGB interprets image bands as Red, Green, Blue and optionally Alpha channels. Colorizers can be chained with or­Else(Colorizer) for trying different strategies until one succeeds.

Since:
1.4

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    Colorizer​.Target
    Information about the computed image to colorize.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Colorizer
    ARGB
    RGB(A) color model for images storing 8 bits integer on 3 or 4 bands.

  • Method Summary

    Modifier and Type
    Method
    Description
    Optional<Color­Model>
    apply(Colorizer​.Target model)
    Returns the color model to use for an image having the given sample model.
    static Colorizer
    for­Categories(Function<Category,Color[]> colors)
    Creates a colorizer which will interpolate colors in ranges identified by categories.
    static Colorizer
    for­Instance(Color­Model colors)
    Creates a colorizer which will use the specified color model instance if compatible with the target.
    static Colorizer
    for­Range(double lower, double upper, Color... colors)
    Creates a colorizer which will interpolate the given colors in the given range of values.
    static Colorizer
    for­Ranges(Map<Number­Range<?>,Color[]> colors)
    Creates a colorizer which will interpolate colors in multiple ranges of values.
    default Colorizer
    or­Else(Colorizer alternative)
    Returns a new colorizer which will apply the specified alternative if this colorizer cannot infer a color model.

    Methods inherited from interface Function

    and­Then, compose

  • Field Details

    • ARGB

      static final Colorizer ARGB
      RGB(A) color model for images storing 8 bits integer on 3 or 4 bands. The color model is RGB for image having 3 bands, or ARGB for images having 4 bands.

  • Method Details

    • forRange

      static Colorizer forRange(double lower, double upper, Color... colors)
      Creates a colorizer which will interpolate the given colors in the given range of values. When the image data type is 8 or 16 bits integer, this colorizer creates Index­Color­Model instances. For other kinds of data type such as floating points, this colorizer creates a non-standard (and potentially slow) color model.

      Limitations

      In current implementation, the non-standard color model ignores the specified colors. If the image data type is not 8 or 16 bits integer, the colors are always grayscale.
      Parameters:
      lower - the minimum sample value, inclusive.
      upper - the maximum sample value, exclusive.
      colors - the colors to use for the specified range of sample values.
      Returns:
      a colorizer which will interpolate the given colors in the given range of values.

    • forRanges

      static Colorizer forRanges(Map<NumberRange<?>,Color[]> colors)
      Creates a colorizer which will interpolate colors in multiple ranges of values. The range of pixel values are specified by Number­Range elements, and the colors to interpolate in each range are specified by Color[] arrays. Empty arrays (i.e. no color) are interpreted as an explicit request for full transparency.

      When the image data type is 8 or 16 bits integer, this colorizer creates Index­Color­Model instances. For other kinds of data type such as floating points, this colorizer creates a non-standard (and potentially slow) color model.

      Default colors

      The given colors map can associate to some keys a null or an empty color arrays. An empty array (i.e. no color) is interpreted as an explicit request for transparency. But null values are interpreted as unspecified colors, in which case the defaults are implementation dependent. In current implementation, the defaults are:
      • If this colorizer is used for visualization, try to keep the existing colors of the image to visualize.
      • Otherwise if the range minimum and maximum values are not equal, default to grayscale colors.
      • Otherwise default to a fully transparent color.

      Limitations

      In current implementation, the non-standard color model ignores the specified colors. If the image data type is not 8 or 16 bits integer, the colors are always grayscale.
      Parameters:
      colors - the colors to use for the specified range of sample values.
      Returns:
      a colorizer which will interpolate the given colors in the given range of values.
      See Also:

    • forCategories

      static Colorizer forCategories(Function<Category,Color[]> colors)
      Creates a colorizer which will interpolate colors in ranges identified by categories. This colorizer is similar to for­Ranges(Map) (with the same limitations) except that instead of mapping colors to predefined ranges of pixel values, it maps colors to category names, units of measurement or other properties. The given function provides a way to colorize images without knowing in advance the numerical values of pixels. For example, instead of specifying "pixel value 0 is blue, 1 is green, 2 is yellow", the given function allows to specify "Lakes are blue, Forests are green, Sand is yellow".

      Default colors

      The given function can return null or empty color arrays for some categories. An empty array (i.e. no color) is interpreted as an explicit request for transparency. But null arrays are interpreted as unrecognized category, in which case the defaults are implementation dependent. In current implementation, the defaults are:
      • If this colorizer is used for visualization, try to keep the existing colors of the image to visualize.
      • Otherwise if all categories are unrecognized, then the colorizer returns an empty value.
      • Otherwise, quantitative categories default to grayscale colors.
      • Otherwise qualitative categories default to a fully transparent color.

      Conditions

      This colorizer is used when Colorizer​.Target​.get­Ranges() provides a non-empty value. That value is typically fetched from the "org.apache.sis.SampleDimensions" image property, which is itself typically fetched from Grid­Coverage​.get­Sample­Dimensions(). If no sample dimension information is available, or if the specified function did not returned at non-null value for at least one category, then this colorizer does not build a color model. A fallback can be specified with or­Else(Colorizer).
      Parameters:
      colors - colors to use for arbitrary categories of sample values.
      Returns:
      a colorizer which will apply colors determined by the Category of sample values.
      See Also:

    • forInstance

      static Colorizer forInstance(ColorModel colors)
      Creates a colorizer which will use the specified color model instance if compatible with the target.
      Parameters:
      colors - the color model instance to use.
      Returns:
      a colorizer which will try to apply the specified color model as-is.

    • apply

      Optional<ColorModel> apply(Colorizer.Target model)
      Returns the color model to use for an image having the given sample model. If this function does not support the creation of a color model for the given sample model, then an empty value is returned. In the latter case, caller will typically fallback on grayscale. Otherwise if a non-empty value is returned, then that color model shall be compatible with the target sample model.
      Specified by:
      apply in interface Function<Colorizer​.Target,Optional<Color­Model>>
      Parameters:
      model - the sample model of the image for which to create a color model.
      Returns:
      the color model to use for the specified sample model.

    • orElse

      default Colorizer orElse(Colorizer alternative)
      Returns a new colorizer which will apply the specified alternative if this colorizer cannot infer a color model.
      Parameters:
      alternative - the alternative strategy for creating a color model.
      Returns:
      a new colorizer which will attempt to apply this first, then fallback on the specified alternative this colorizer did not produced a result.