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

# Interface Colorizer

All Superinterfaces:
  `Function<Colorizer​.Target,Optional<ColorModel>>`

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 `ImageProcessor` needs a new color model for the computation result. The `Colorizer​.Target` argument contains information about the image to colorize, in particular the `SampleModel` 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 `orElse(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<ColorModel>`
  `apply(Colorizer​.Target model)`
  Returns the color model to use for an image having the given sample model.
  `static Colorizer`
  `forCategories(Function<Category,Color[]> colors)`
  Creates a colorizer which will interpolate colors in ranges identified by categories.
  `static Colorizer`
  `forInstance(ColorModel colors)`
  Creates a colorizer which will use the specified color model instance if compatible with the target.
  `static Colorizer`
  `forRange(double lower, double upper, Color... colors)`
  Creates a colorizer which will interpolate the given colors in the given range of values.
  `static Colorizer`
  `forRanges(Map<NumberRange<?>,Color[]> colors)`
  Creates a colorizer which will interpolate colors in multiple ranges of values.
  `default Colorizer`
  `orElse(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

  `andThen, 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 `IndexColorModel` 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 `NumberRange` 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 `IndexColorModel` 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:
      - `ImageProcessor​.visualize(RenderedImage)`

  - ### 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 `forRanges(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​.getRanges()` provides a non-empty value. That value is typically fetched from the "org.apache.sis.SampleDimensions" image property, which is itself typically fetched from `GridCoverage​.getSampleDimensions()`. 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 `orElse(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:
      - `ImageProcessor​.visualize(RenderedImage)`

  - ### 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<ColorModel>>`
    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.