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, Image­Processor 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 Rendered­Image implementations are executed sequentially in the caller thread, for safety reasons. Some operations can be parallelized, but it should be enabled only if the Rendered­Image is known to be thread-safe and has concurrent (or fast) implementation of Rendered­Image​.get­Tile(int, int). Apache SIS implementations of Rendered­Image 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 Imaging­Op­Exception, in which case no result is available. But errors can also be notified as a Log­Record 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 Image­Processor 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 Math­Transform 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, Rendered­Image 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 Image­Processor 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 Image­Processor​.Mode​.PARALLEL.

Error handling

If an exception occurs during the computation of a tile, then the Image­Processor behavior is controlled by the error­Handler property:
  • If Error­Handler​.THROW, the exception is wrapped in an Imaging­Op­Exception and thrown.
  • If Error­Handler​.LOG, the exception is logged and a partial result is returned.
  • If any other value, the exception is wrapped in a Log­Record 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

Image­Processor is safe for concurrent use in multi-threading environment. Note however that Image­Processor instances are mutable; consider cloning if setter methods are invoked on a shared instance.
Since:
1.1
See Also:

Defined in the sis-feature module

  • Constructor Details

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

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

    • 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 set­Fill­Values(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​.Na­N or Double​.Na­N 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 set­Category­Colors(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​.get­Sample­Range().

      This function is used by methods expecting Sample­Dimension arguments such as visualize(Rendered­Image, 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 Image­Processor 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 Image­Processor 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 Image­Processor aims for the best accuracy it can produce. If the returned array is non-empty and contains accuracies large enough, Image­Processor 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 Image­Processor 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, Image­Processor recognizes only accuracies in Units​.PIXEL. A value such as 0.125 pixel may cause Image­Processor 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 Image­Processor​.Mode​.SEQUENTIAL, operations are executed sequentially in the caller thread. If Image­Processor​.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 Image­Processor​.Mode​.PARALLEL if the Rendered­Image instances are thread-safe and provide a concurrent (or very fast) implementation of Rendered­Image​.get­Tile(int, int). If Image­Processor​.Mode​.SEQUENTIAL, only the caller thread is used. Sequential operations may be useful for processing Rendered­Image implementations that may not be thread-safe.

      It is safe to set this flag to Image­Processor​.Mode​.PARALLEL with Buffered­Image or with Apache SIS implementations of Rendered­Image.

      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 Error­Handler​.THROW (the default), exceptions are wrapped in Imaging­Op­Exception and thrown. If Error­Handler​.LOG, exceptions are wrapped in a Log­Record, 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 Imaging­Op­Exception and throw them. If this property is set to Error­Handler​.LOG, then exceptions will be wrapped in Log­Record 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 Image­Processor 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 Error­Handler​.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(Rendered­Image, Shape) and extracting immediately the statistics property value, except that errors are handled by the error handler.

      If area­Of­Interest 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:

      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.
      area­Of­Interest - pixel coordinates of the area of interest, or null for the default.
      Returns:
      the statistics of sample values in each band.
      Throws:
      Imaging­Op­Exception - if an error occurred during calculation and the error handler is Error­Handler​.THROW.
      See Also:

    • 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 area­Of­Interest 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:
      Parameters:
      source - the image for which to provide statistics.
      area­Of­Interest - 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:

    • 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 Rendered­Image
      "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:
      Illegal­Argument­Exception - 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:
      Illegal­Argument­Exception - 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 Writable­Rendered­Image and the given converters are invertible, then the returned image will also be a Writable­Rendered­Image 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 source­Ranges 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.
      source­Ranges - 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.
      target­Type - the type of image resulting from conversions.
      color­Model - 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 get­Interpolation().

      If the given source is an instance of Resampled­Image, 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:

      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 Image­Processor​.Resizing​.EXPAND policy is applied.
      to­Source - 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:
      Parameters:
      source - the image to compute immediately (may be null).
      area­Of­Interest - 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:
      Imaging­Op­Exception - if an exception occurred during Rendered­Image​.get­Tile(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 Index­Color­Model. 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 Index­Color­Model.

      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 Index­Color­Model. 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 Index­Color­Model.

      This method is similar to visualize(Rendered­Image, Map) except that the Map argument is splitted in two parts: the ranges (map keys) are encapsulated in Category objects, themselves encapsulated in Sample­Dimension 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:
      Parameters:
      source - the image to recolor for visualization purposes.
      ranges - description of source bands, or null if none. This is typically obtained by Grid­Coverage​.get­Sample­Dimensions().
      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, to­Source)
      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:
      Parameters:
      source - the image to be resampled and recolored.
      bounds - domain of pixel coordinates of resampled image to create. Updated by this method if Image­Processor​.Resizing​.EXPAND policy is applied.
      to­Source - conversion of pixel coordinates from resampled image to source image.
      ranges - description of source bands, or null if none. This is typically obtained by Grid­Coverage​.get­Sample­Dimensions().
      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:
      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.
      grid­To­CRS - 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:
      Imaging­Op­Exception - 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:
      hash­Code 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.