Package org.apache.sis.image

# Class ImageProcessor

Object
ImageProcessor

All Implemented Interfaces:
  `Cloneable`

public class ImageProcessor extends Object implements Cloneable
A predefined set of operations on images as convenience methods. After instantiation, `ImageProcessor` can be configured for the following aspects:

- Interpolation method to use during resampling operations.
- Fill values to use for pixels that can not be computed.
- Category colors for mapping sample values (identified by their range, name or unit of measurement) to colors.
- Image resizing policy to apply if a requested image size prevent the image to be tiled.
- Positional accuracy hints for enabling the use of faster algorithm when a lower accuracy is acceptable.
- Whether operations can be executed in parallel. By default operations on unknown `RenderedImage` implementations are executed sequentially in the caller thread, for safety reasons. Some operations can be parallelized, but it should be enabled only if the `RenderedImage` is known to be thread-safe and has concurrent (or fast) implementation of `RenderedImage​.getTile(int, int)`. Apache SIS implementations of `RenderedImage` can be parallelized, but it may not be the case of images from other libraries.
- Whether the operations should fail if an exception is thrown while processing a tile. By default errors during calculation are propagated as an `ImagingOpException`, in which case no result is available. But errors can also be notified as a `LogRecord` instead, in which case partial results may be available.

For each image operations, above properties are combined with parameters given to the operation method. Each method in this `ImageProcessor` class documents the properties used in addition of method parameters.
API design: properties (setter methods) are used for values that can be applied unchanged on many different images. For example the interpolation method can be specified once and used unchanged for many `resample(…)` operations. On the other hand, method arguments are used for values that are usually specific to the image to process. For example the `MathTransform` argument given to the `resample(…)` operation depends tightly on the source image and destination bounds (also given in arguments); those information usually need to be recomputed for each image.

## Deferred calculations

Methods in this class may compute the result at some later time after the method returned, instead of computing the result immediately on method call. Consequently unless otherwise specified, `RenderedImage` arguments should be stable, i.e. pixel values should not be modified after method return.

## Area of interest

Some operations accept an optional area of interest argument specified as a `Shape` instance in pixel coordinates. If a shape is given, it should not be modified after `ImageProcessor` method call because the given object may be retained directly (i.e. the `Shape` is not always cloned; it depends on its class). In addition, the `Shape` implementation shall be thread-safe (assuming its state stay unmodified) unless the execution mode is set to `ImageProcessor​.Mode​.PARALLEL`.

## Error handling

If an exception occurs during the computation of a tile, then the `ImageProcessor` behavior is controlled by the `errorHandler` property:

- If `ErrorHandler​.THROW`, the exception is wrapped in an `ImagingOpException` and thrown.
- If `ErrorHandler​.LOG`, the exception is logged and a partial result is returned.
- If any other value, the exception is wrapped in a `LogRecord` and sent to that filter. The filter can store the log record, for example for showing later in a graphical user interface (GUI). If the filter returns `true`, the log record is also logged, otherwise it is silently discarded. In both cases a partial result is returned.

## Thread-safety

`ImageProcessor` is safe for concurrent use in multi-threading environment. Note however that `ImageProcessor` instances are mutable; consider cloning if setter methods are invoked on a shared instance.

Since:
  1.1
See Also:
  - `GridCoverageProcessor`

Defined in the `sis-feature` module

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `ImageProcessor​.Mode`
  Execution modes specifying whether operations can be executed in parallel.
  `static enum`
  `ImageProcessor​.Resizing`
  Whether `ImageProcessor` can produce an image of different size compared to requested size.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `ImageProcessor()`
  Creates a new processor with default configuration.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `ImageProcessor`
  `clone()`
  Returns an image processor with the same configuration than this processor.
  `RenderedImage`
  `convert(RenderedImage source, NumberRange<?>[] sourceRanges, MathTransform1D[] converters, DataType targetType, ColorModel colorModel)`
  Returns an image with sample values converted by the given functions.
  `boolean`
  `equals(Object object)`
  Returns `true` if the given object is an image processor of the same class with the same configuration.
  `Function<Category,Color[]>`
  `getCategoryColors()`
  Returns the colors to use for given categories of sample values, or `null` is unspecified.
  `ErrorHandler`
  `getErrorHandler()`
  Returns whether exceptions occurring during computation are propagated or logged.
  `ImageProcessor​.Mode`
  `getExecutionMode()`
  Returns whether operations can be executed in parallel.
  `Number[]`
  `getFillValues()`
  Returns the values to use for pixels that can not be computed.
  `ImageProcessor​.Resizing`
  `getImageResizingPolicy()`
  Returns whether `ImageProcessor` can produce an image of different size compared to requested size.
  `Interpolation`
  `getInterpolation()`
  Returns the interpolation method to use during resample operations.
  `Quantity<?>[]`
  `getPositionalAccuracyHints()`
  Returns hints about the desired positional accuracy, in "real world" units or in pixel units.
  `int`
  `hashCode()`
  Returns a hash code value for this image processor based on its current configuration.
  `List<NavigableMap<Double,Shape>>`
  `isolines(RenderedImage data, double[][] levels, MathTransform gridToCRS)`
  Generates isolines at the specified levels computed from data provided by the given image.
  `RenderedImage`
  `prefetch(RenderedImage source, Rectangle areaOfInterest)`
  Computes immediately all tiles in the given region of interest, then return an image will those tiles ready.
  `RenderedImage`
  `resample(RenderedImage source, Rectangle bounds, MathTransform toSource)`
  Creates a new image which will resample the given image.
  `RenderedImage`
  `selectBands(RenderedImage source, int... bands)`
  Selects a subset of bands in the given image.
  `void`
  `setCategoryColors(Function<Category,Color[]> colors)`
  Sets the colors to use for given categories in image, or `null` is unspecified.
  `void`
  `setErrorHandler(ErrorHandler handler)`
  Sets whether exceptions occurring during computation are propagated or logged.
  `void`
  `setExecutionMode(ImageProcessor​.Mode mode)`
  Sets whether operations can be executed in parallel.
  `void`
  `setFillValues(Number... values)`
  Sets the values to use for pixels that can not be computed.
  `void`
  `setImageResizingPolicy(ImageProcessor​.Resizing policy)`
  Sets whether `ImageProcessor` can produce an image of different size compared to requested size.
  `void`
  `setInterpolation(Interpolation method)`
  Sets the interpolation method to use during resample operations.
  `void`
  `setPositionalAccuracyHints(Quantity<?>... hints)`
  Sets hints about desired positional accuracy, in "real world" units or in pixel units.
  `RenderedImage`
  `statistics(RenderedImage source, Shape areaOfInterest)`
  Returns an image with statistics (minimum, maximum, mean, standard deviation) on each bands.
  `RenderedImage`
  `stretchColorRamp(RenderedImage source, Map<String,?> modifiers)`
  Returns an image with the same sample values than the given image, but with its color ramp stretched between specified or inferred bounds.
  `Statistics[]`
  `valueOfStatistics(RenderedImage source, Shape areaOfInterest)`
  Returns statistics (minimum, maximum, mean, standard deviation) on each bands of the given image.
  `RenderedImage`
  `visualize(RenderedImage source, Rectangle bounds, MathTransform toSource, List<SampleDimension> ranges)`
  Returns an image as the resampling of the given image followed by a conversion to integer sample values.
  `RenderedImage`
  `visualize(RenderedImage source, List<SampleDimension> ranges)`
  Returns an image where all sample values are indices of colors in an `IndexColorModel`.
  `RenderedImage`
  `visualize(RenderedImage source, Map<NumberRange<?>,Color[]> colors)`
  Returns an image where all sample values are indices of colors in an `IndexColorModel`.

  ### Methods inherited from class Object

  `finalize, getClass, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### ImageProcessor

    public ImageProcessor()
    Creates a new processor with default configuration. The execution mode is initialized to `ImageProcessor​.Mode​.DEFAULT` and the error handler to `ErrorHandler​.THROW`.

- ## Method Details

  - ### getInterpolation

    public Interpolation getInterpolation()
    Returns the interpolation method to use during resample operations.
    Returns:
      interpolation method to use during resample operations.
    See Also:
      - `resample(RenderedImage, Rectangle, MathTransform)`

  - ### setInterpolation

    public void setInterpolation(Interpolation method)
    Sets the interpolation method to use during resample operations.
    Parameters:
      `method` - interpolation method to use during resample operations.
    See Also:
      - `resample(RenderedImage, Rectangle, MathTransform)`

  - ### getFillValues

    public Number[] getFillValues()
    Returns the values to use for pixels that can not be computed. This method returns a copy of the array set by the last call to `setFillValues(Number...)`.
    Returns:
      fill values to use for pixels that can not be computed, or `null` for the defaults.

  - ### setFillValues

    public void setFillValues(Number... values)
    Sets the values to use for pixels that can not be computed. The given array may be `null` or may contain `null` elements for default values. Those defaults are zero for images storing sample values as integers, or `Float​.NaN` or `Double​.NaN` for images storing sample values as floating point numbers. If the given array contains less elements than the number of bands in an image, missing elements will be assumed null. If the given array contains more elements than the number of bands, extraneous elements will be ignored.
    Parameters:
      `values` - fill values to use for pixels that can not be computed, or `null` for the defaults.

  - ### getCategoryColors

    public Function<Category,Color[]> getCategoryColors()
    Returns the colors to use for given categories of sample values, or `null` is unspecified. This method returns the function set by the last call to `setCategoryColors(Function)`.
    Returns:
      colors to use for arbitrary categories of sample values, or `null` for default.

  - ### setCategoryColors

    public void setCategoryColors(Function<Category,Color[]> colors)
    Sets the colors to use for given categories in image, or `null` is unspecified. This function provides a way to colorize images without knowing in advance the numerical values of pixels. For example instead of specifying "pixel value 0 in blue, 1 in green, 2 in yellow", this function allows to specify "Lakes in blue, Forests in green, Sand in yellow". It is still possible however to use numerical values if the function desires to do so, since this information is available with `Category​.getSampleRange()`.

    This function is used by methods expecting `SampleDimension` arguments such as `visualize(RenderedImage, List)`. The given function can return `null` or empty arrays for some categories, which are interpreted as fully transparent pixels.

    Parameters:
      `colors` - colors to use for arbitrary categories of sample values, or `null` for default.

  - ### getImageResizingPolicy

    public ImageProcessor.Resizing getImageResizingPolicy()
    Returns whether `ImageProcessor` can produce an image of different size compared to requested size. If this processor can use a different size, the enumeration value specifies what kind of changes may be applied.
    Returns:
      the image resizing policy.

  - ### setImageResizingPolicy

    public void setImageResizingPolicy(ImageProcessor.Resizing policy)
    Sets whether `ImageProcessor` can produce an image of different size compared to requested size.
    Parameters:
      `policy` - the new image resizing policy.

  - ### getPositionalAccuracyHints

    public Quantity<?>[] getPositionalAccuracyHints()
    Returns hints about the desired positional accuracy, in "real world" units or in pixel units. This is an empty array by default, which means that `ImageProcessor` aims for the best accuracy it can produce. If the returned array is non-empty and contains accuracies large enough, `ImageProcessor` may use some slightly faster algorithms at the expense of accuracy.
    Returns:
      desired accuracy in no particular order, or an empty array if none.

  - ### setPositionalAccuracyHints

    public void setPositionalAccuracyHints(Quantity<?>... hints)
    Sets hints about desired positional accuracy, in "real world" units or in pixel units. More than one hint can be specified for allowing the use of different units. For example the given array can contain an accuracy in metres and an accuracy in seconds, for specifying desired accuracies in both spatial dimensions and in the temporal dimension. Accuracy can also be specified in both real world units such as metres and in pixel units, which are converted to real world units depending on image resolution. If more than one value is applicable to a dimension (after unit conversion if needed), the smallest value is taken.

    Those values are only hints, the `ImageProcessor` is free to ignore them. In any cases there is no guarantees that computed images will met those accuracies. The given values are honored on a best effort basis only.

    In current implementation, `ImageProcessor` recognizes only accuracies in `Units​.PIXEL`. A value such as 0.125 pixel may cause `ImageProcessor` to use some a slightly faster algorithm at the expense of accuracy during resampling operations.

    Parameters:
      `hints` - desired accuracy in no particular order, or a `null` array if none. Null elements in the array are ignored.

  - ### getExecutionMode

    public ImageProcessor.Mode getExecutionMode()
    Returns whether operations can be executed in parallel. If `ImageProcessor​.Mode​.SEQUENTIAL`, operations are executed sequentially in the caller thread. If `ImageProcessor​.Mode​.PARALLEL`, some operations may be parallelized using an arbitrary number of threads.
    Returns:
      whether the operations can be executed in parallel.

  - ### setExecutionMode

    public void setExecutionMode(ImageProcessor.Mode mode)
    Sets whether operations can be executed in parallel. This value can be set to `ImageProcessor​.Mode​.PARALLEL` if the `RenderedImage` instances are thread-safe and provide a concurrent (or very fast) implementation of `RenderedImage​.getTile(int, int)`. If `ImageProcessor​.Mode​.SEQUENTIAL`, only the caller thread is used. Sequential operations may be useful for processing `RenderedImage` implementations that may not be thread-safe.

    It is safe to set this flag to `ImageProcessor​.Mode​.PARALLEL` with `BufferedImage` or with Apache SIS implementations of `RenderedImage`.

    Parameters:
      `mode` - whether the operations can be executed in parallel.

  - ### getErrorHandler

    public ErrorHandler getErrorHandler()
    Returns whether exceptions occurring during computation are propagated or logged. If `ErrorHandler​.THROW` (the default), exceptions are wrapped in `ImagingOpException` and thrown. If `ErrorHandler​.LOG`, exceptions are wrapped in a `LogRecord`, filtered then eventually logged.
    Returns:
      whether exceptions occurring during computation are propagated or logged.

  - ### setErrorHandler

    public void setErrorHandler(ErrorHandler handler)
    Sets whether exceptions occurring during computation are propagated or logged. The default behavior is to wrap exceptions in `ImagingOpException` and throw them. If this property is set to `ErrorHandler​.LOG`, then exceptions will be wrapped in `LogRecord` instead, in which case a partial result may be available. Only one log record is created for all tiles that failed for the same operation on the same image.

    #### Limitations

    In current `ImageProcessor` implementation, the error handler is not honored by all operations. Some operations may continue to throw an exception on failure (the behavior of default error handler) even if a different handler has been specified. Each operation specifies in its Javadoc whether the operation uses error handler or not.
    Parameters:
      `handler` - handler to notify when an operation failed on one or more tiles, or `ErrorHandler​.THROW` for propagating the exception.

  - ### valueOfStatistics

    public Statistics[] valueOfStatistics(RenderedImage source, Shape areaOfInterest)
    Returns statistics (minimum, maximum, mean, standard deviation) on each bands of the given image. Invoking this method is equivalent to invoking `statistics(RenderedImage, Shape)` and extracting immediately the statistics property value, except that errors are handled by the error handler.

    If `areaOfInterest` is `null`, then the default is as below:

    - If the "org.apache.sis.Statistics" property value exists in the given image, then that value is returned. Note that they are not necessarily statistics for the whole image. They are whatever statistics the property provided considered as representative.
    - Otherwise statistics are computed for the whole image.

    #### Properties used

    This operation uses the following properties in addition to method parameters:
    - Execution mode (parallel or sequential).
    - Error handler (custom action executed if an exception is thrown).

    #### Result relationship with source

    This method computes statistics immediately. Changes in the `source` image after this method call do not change the results.
    Parameters:
      `source` - the image for which to compute statistics.
      `areaOfInterest` - pixel coordinates of the area of interest, or `null` for the default.
    Returns:
      the statistics of sample values in each band.
    Throws:
      `ImagingOpException` - if an error occurred during calculation and the error handler is `ErrorHandler​.THROW`.
    See Also:
      - `statistics(RenderedImage, Shape)`
      - `PlanarImage​.STATISTICS_KEY`

  - ### statistics

    public RenderedImage statistics(RenderedImage source, Shape areaOfInterest)
    Returns an image with statistics (minimum, maximum, mean, standard deviation) on each bands. The property value will be computed when first requested (it is not computed immediately by this method).

    If `areaOfInterest` is `null`, then the default is as below:

    - If the "org.apache.sis.Statistics" property value exists in the given image, then that image is returned as-is. Note that the existing property value is not necessarily statistics for the whole image. They are whatever statistics the property provider considers as representative.
    - Otherwise an image augmented with a "org.apache.sis.Statistics" property value is returned.

    #### Properties used

    This operation uses the following properties in addition to method parameters:
    - Execution mode (parallel or sequential).
    - Error handler (whether to fail if an exception is thrown).
    Parameters:
      `source` - the image for which to provide statistics.
      `areaOfInterest` - pixel coordinates of the area of interest, or `null` for the default.
    Returns:
      an image with an "org.apache.sis.Statistics" property. May be `image` if the given argument already has a statistics property.
    See Also:
      - `valueOfStatistics(RenderedImage, Shape)`
      - `PlanarImage​.STATISTICS_KEY`

  - ### stretchColorRamp

    public RenderedImage stretchColorRamp(RenderedImage source, Map<String,?> modifiers)
    Returns an image with the same sample values than the given image, but with its color ramp stretched between specified or inferred bounds. For example in a gray scale image, pixels with the minimum value will be black and pixels with the maximum value will be white. This operation is a kind of tone mapping, a technique used in image processing to map one set of colors to another. The mapping applied by this method is conceptually a simple linear transform (a scale and an offset) applied on sample values before they are mapped to their colors.

    The minimum and maximum value can be either specified explicitly, or determined from `statistics` on the image. In the later case a range of value is determined first from the minimum and maximum values found in the image, optionally narrowed to an interval of some standard deviations around the mean value.

    Narrowing with standard deviations is useful for data having a Gaussian distribution, as often seen in nature. In such distribution, 99.9% of the data are between the mean ± 3×standard deviation, but some values may still appear much further. The minimum and maximum values alone are not a robust way to compute a range of values for the color ramp because a single value very far from other values is sufficient for making the colors difficult to distinguish for 99.9% of the data.

    The range of values for the color ramp can be narrowed with following modifiers (a `Map` is used for allowing addition of more modifiers in future Apache SIS versions). All unrecognized modifiers are silently ignored. If no modifier is specified, then the color ramp will be stretched from minimum to maximum values found in specified image.

    Value range modifiers
    Key | Purpose | Values
    --- | --- | ---
    `"minimum"` | Minimum value (omitted if computed from statistics). | `Number`
    `"maximum"` | Maximum value (omitted if computed from statistics). | `Number`
    `"multStdDev"` | Multiple of the standard deviation. | `Number` (typical values: 1.5, 2 or 3)
    `"statistics"` | Statistics or image from which to get statistics. | `Statistics` or `RenderedImage`
    `"areaOfInterest"` | Pixel coordinates of the region for which to compute statistics. | `Shape`
    `"sampleDimensions"` | Meaning of pixel values. | `SampleDimension`

    #### Properties used

    This operation uses the following properties in addition to method parameters:
    - (none)

    #### Limitation

    Current implementation can stretch only gray scale images (a future version may extend support to images using index color models). If this method can not stretch the color ramp, for example because the given image is an RGB image, then the image is returned unchanged.
    Parameters:
      `source` - the image to recolor.
      `modifiers` - modifiers for narrowing the range of values, or `null` if none.
    Returns:
      the image with color ramp stretched between the specified or calculated bounds, or `image` unchanged if the operation can not be applied on the given image.
    Throws:
      `IllegalArgumentException` - if the value associated to one of about keys is not of expected type.

  - ### selectBands

    public RenderedImage selectBands(RenderedImage source, int... bands)
    Selects a subset of bands in the given image. This method can also be used for changing band order or repeating the same band from the source image. If the specified `bands` are the same than the source image bands in the same order, then `source` is returned directly.

    This method returns an image sharing the same data buffer than the source image; pixel values are not copied. Consequently changes in the source image are reflected immediately in the returned image.

    #### Properties used

    This operation uses the following properties in addition to method parameters:
    - (none)
    Parameters:
      `source` - the image in which to select bands.
      `bands` - indices of bands to retain.
    Returns:
      image width selected bands.
    Throws:
      `IllegalArgumentException` - if a band index is invalid.

  - ### convert

    public RenderedImage convert(RenderedImage source, NumberRange<?>[] sourceRanges, MathTransform1D[] converters, DataType targetType, ColorModel colorModel)
    Returns an image with sample values converted by the given functions. The results can be stored as `byte`, `short`, `int`, `float` or `double` values, not necessarily the same type than the source values. If the result values are stored as integers, then they are rounded to nearest integers and clamped in the valid range of the target integer type.

    If the source image is a `WritableRenderedImage` and the given converters are invertible, then the returned image will also be a `WritableRenderedImage` instance. In such case values written in the returned image will be reflected in the source image, with rounding and clamping if the source values are stored as integers.

    The number of bands in the returned image is the length of the `converters` array, which must be greater than 0 and not greater than the number of bands in the source image. If the `converters` array length is less than the number of source bands, all source bands at index ≥ `converters​.length` will be ignored.

    The `sourceRanges` array is only a hint for this method. The array may be `null` or contain `null` elements, and may be of any length. Missing elements are considered null and extraneous elements are ignored. Those ranges do not need to encompass all possible values; it is sufficient to provide only typical or "most interesting" ranges.

    #### Properties used

    This operation uses the following properties in addition to method parameters:
    - (none)

    #### Result relationship with source

    Changes in the source image are reflected in the returned images if the source image notifies tile observers.
    Parameters:
      `source` - the image for which to convert sample values.
      `sourceRanges` - approximate ranges of values for each band in source image, or `null` if unknown.
      `converters` - the transfer functions to apply on each band of the source image.
      `targetType` - the type of image resulting from conversions.
      `colorModel` - color model of resulting image, or `null`.
    Returns:
      the image which compute converted values from the given source.

  - ### resample

    public RenderedImage resample(RenderedImage source, Rectangle bounds, MathTransform toSource)
    Creates a new image which will resample the given image. The resampling operation is defined by a potentially non-linear transform from the new image to the specified source image. That transform should map pixel centers. If that transform produces coordinates that are outside source envelope bounds, then the corresponding pixels in the new image are set to fill values. Otherwise sample values are interpolated using the method given by `getInterpolation()`.

    If the given source is an instance of `ResampledImage`, then this method will use the source of the given source. The intent is to avoid resampling a resampled image; instead this method works on the original data.

    #### Properties used

    This operation uses the following properties in addition to method parameters:
    - Interpolation method (nearest neighbor, bilinear, etc).
    - Fill values for pixels outside source image.
    - Image resizing policy to apply if `bounds` size is not divisible by a tile size.
    - Positional accuracy hints for enabling faster resampling at the cost of lower precision.

    #### Result relationship with source

    Changes in the source image are reflected in the returned images if the source image notifies tile observers.
    Parameters:
      `source` - the image to be resampled.
      `bounds` - domain of pixel coordinates of resampled image to create. Updated by this method if `ImageProcessor​.Resizing​.EXPAND` policy is applied.
      `toSource` - conversion of pixel coordinates from resampled image to `source` image.
    Returns:
      resampled image (may be `source`).

  - ### prefetch

    public RenderedImage prefetch(RenderedImage source, Rectangle areaOfInterest)
    Computes immediately all tiles in the given region of interest, then return an image will those tiles ready. Computations will use many threads if execution mode is parallel.

    #### Properties used

    This operation uses the following properties in addition to method parameters:
    - Execution mode (parallel or sequential).
    - Error handler (whether to fail if an exception is thrown).
    Parameters:
      `source` - the image to compute immediately (may be `null`).
      `areaOfInterest` - pixel coordinates of the region to prefetch, or `null` for the whole image.
    Returns:
      image with all tiles intersecting the AOI computed, or `null` if the given image was null.
    Throws:
      `ImagingOpException` - if an exception occurred during `RenderedImage​.getTile(int, int)` call. This exception wraps the original exception as its cause.

  - ### visualize

    public RenderedImage visualize(RenderedImage source, Map<NumberRange<?>,Color[]> colors)
    Returns an image where all sample values are indices of colors in an `IndexColorModel`. If the given image stores sample values as unsigned bytes or short integers, then those values are used as-is (they are not copied or converted). Otherwise this operation will convert sample values to unsigned bytes in order to enable the use of `IndexColorModel`.

    The given map specifies the color to use for different ranges of values in the source image. The ranges of values in the returned image may not be the same; this method is free to rescale them. The `Color` arrays may have any length; colors will be interpolated as needed for fitting the ranges of values in the destination image.

    The resulting image is suitable for visualization purposes, but should not be used for computation purposes. There is no guarantees about the number of bands in returned image or about which formula is used for converting floating point values to integer values.

    #### Properties used

    This operation uses the following properties in addition to method parameters:
    - (none)
    Parameters:
      `source` - the image to recolor for visualization purposes.
      `colors` - colors to use for each range of values in the source image.
    Returns:
      recolored image for visualization purposes only.

  - ### visualize

    public RenderedImage visualize(RenderedImage source, List<SampleDimension> ranges)
    Returns an image where all sample values are indices of colors in an `IndexColorModel`. If the given image stores sample values as unsigned bytes or short integers, then those values are used as-is (they are not copied or converted). Otherwise this operation will convert sample values to unsigned bytes in order to enable the use of `IndexColorModel`.

    This method is similar to `visualize(RenderedImage, Map)` except that the `Map` argument is splitted in two parts: the ranges (map keys) are encapsulated in `Category` objects, themselves encapsulated in `SampleDimension` objects. The colors (map values) are determined by a function receiving `Category` inputs. This separation makes easier to apply colors based on criterion other than numerical values. For example colors could be determined from category name such as "Temperature", or units of measurement. The `Color` arrays may have any length; colors will be interpolated as needed for fitting the ranges of values in the destination image.

    The resulting image is suitable for visualization purposes, but should not be used for computation purposes. There is no guarantees about the number of bands in returned image or about which formula is used for converting floating point values to integer values.

    #### Properties used

    This operation uses the following properties in addition to method parameters:
    - Category colors.
    Parameters:
      `source` - the image to recolor for visualization purposes.
      `ranges` - description of `source` bands, or `null` if none. This is typically obtained by `GridCoverage​.getSampleDimensions()`.
    Returns:
      recolored image for visualization purposes only.

  - ### visualize

    public RenderedImage visualize(RenderedImage source, Rectangle bounds, MathTransform toSource, List<SampleDimension> ranges)
    Returns an image as the resampling of the given image followed by a conversion to integer sample values. This is a combination of the following methods, as a single image operation for avoiding creation of an intermediate image step:
    1. `resample(source, bounds, toSource)`
    2. `visualize(resampled, ranges)`
    Combining above steps may be advantageous when the `resample(…)` result is not needed for anything else than visualization. If the same resampling may be needed for computational purposes, then it may be more advantageous to keep above method calls separated instead of using this `visualize(…)` method.

    The resulting image is suitable for visualization purposes, but should not be used for computation purposes. There is no guarantees about the number of bands in returned image or about which formula is used for converting floating point values to integer values.

    #### Properties used

    This operation uses the following properties in addition to method parameters:
    - Interpolation method (nearest neighbor, bilinear, etc).
    - Fill values for pixels outside source image.
    - Image resizing policy to apply if `bounds` size is not divisible by a tile size.
    - Positional accuracy hints for enabling faster resampling at the cost of lower precision.
    - Category colors.
    Parameters:
      `source` - the image to be resampled and recolored.
      `bounds` - domain of pixel coordinates of resampled image to create. Updated by this method if `ImageProcessor​.Resizing​.EXPAND` policy is applied.
      `toSource` - conversion of pixel coordinates from resampled image to `source` image.
      `ranges` - description of `source` bands, or `null` if none. This is typically obtained by `GridCoverage​.getSampleDimensions()`.
    Returns:
      resampled and recolored image for visualization purposes only.

  - ### isolines

    public List<NavigableMap<Double,Shape>> isolines(RenderedImage data, double[][] levels, MathTransform gridToCRS)
    Generates isolines at the specified levels computed from data provided by the given image. Isolines will be computed for every bands in the given image. For each band, the result is given as a `Map` where keys are the specified `levels` and values are the isolines at the associated level. If there is no isoline for a given level, there will be no corresponding entry in the map.

    #### Properties used

    This operation uses the following properties in addition to method parameters:
    - Execution mode (parallel or sequential).
    Parameters:
      `data` - image providing source values.
      `levels` - values for which to compute isolines. An array should be provided for each band. If there is more bands than `levels​.length`, the last array is reused for all remaining bands.
      `gridToCRS` - transform from pixel coordinates to geometry coordinates, or `null` if none. Integer source coordinates are located at pixel centers.
    Returns:
      the isolines for specified levels in each band. The `List` size is the number of bands. For each band, the `Map` size is equal or less than `levels[band].length`. Map keys are the specified levels, excluding those for which there is no isoline. Map values are the isolines as a Java2D `Shape`.
    Throws:
      `ImagingOpException` - if an error occurred during calculation.

  - ### equals

    public boolean equals(Object object)
    Returns `true` if the given object is an image processor of the same class with the same configuration.
    Overrides:
      `equals` in class `Object`
    Parameters:
      `object` - the other object to compare with this processor.
    Returns:
      whether the other object is an image processor of the same class with the same configuration.

  - ### hashCode

    public int hashCode()
    Returns a hash code value for this image processor based on its current configuration.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      a hash code value for this processor.

  - ### clone

    public ImageProcessor clone()
    Returns an image processor with the same configuration than this processor.
    Overrides:
      `clone` in class `Object`
    Returns:
      a clone of this image processor.