Package org.apache.sis.image

Class StatisticsCalculator

java.lang.Object
org.apache.sis.image.PlanarImage
org.apache.sis.image.ImageAdapter
org.apache.sis.image.AnnotatedImage
org.apache.sis.image.StatisticsCalculator
All Implemented Interfaces:
RenderedImage
final class StatisticsCalculator extends AnnotatedImage
Computes statistics on all pixel values of an image. The results are stored in an array of Statistics objects (one per band) in a property named "org.apache.sis.Statistics". The statistics can be computed in parallel or sequentially for non thread-safe images.
Since:
1.1
Version:
1.2

  • Field Details

    • sampleFilters

      private final DoubleUnaryOperator[] sampleFilters
      An optional function for converting values before to add them to statistics. The main purpose is to exclude "no data" values by replacing them by NaN. If non-null, the length of this array must be equal to the number of bands. Array may contain null elements if no filter should be applied for a band.

  • Constructor Details

    • StatisticsCalculator

      StatisticsCalculator(RenderedImage image, Shape areaOfInterest, DoubleUnaryOperator[] sampleFilters, boolean parallel, boolean failOnException)
      Creates a new calculator.
      Parameters:
      image - the image for which to compute statistics.
      areaOfInterest - pixel coordinates of AOI, or null for the whole image.
      sampleFilters - converters to apply on sample values before to add them to statistics, or null.
      parallel - whether parallel execution is authorized.
      failOnException - whether errors occurring during computation should be propagated.

  • Method Details

    • getExtraParameter

      final Object[] getExtraParameter()
      Returns the optional filter parameter. This is used by parent class for caching and for AnnotatedImage.equals(Object) and AnnotatedImage.hashCode() implementations.
      Overrides:
      getExtraParameter in class AnnotatedImage
      Returns:
      subclass specific extra parameter, or null if none.

    • getComputedPropertyName

      protected String getComputedPropertyName()
      Returns the name of the property which is computed by this image.
      Specified by:
      getComputedPropertyName in class AnnotatedImage
      Returns:
      name of property computed by this image. Shall not be null.

    • createAccumulator

      private static Statistics[] createAccumulator(int numBands)
      Creates the objects where to add sample values for computing statistics. We will have one accumulator for each band in the source image. This is used for both sequential and parallel executions.

    • filtered

      private DoubleConsumer[] filtered(Statistics[] accumulator)
      Returns accumulators which will apply the #filter before to add values to statistics. If there is no filter to apply, then this method returns the accumulator array directly.
      Parameters:
      accumulator - where to accumulate the statistics results.
      Returns:
      the accumulator optionally filtered.

    • compute

      private void compute(DoubleConsumer[] accumulator, PixelIterator it)
      Computes statistics using the given iterator and accumulates the result for all bands. This method is invoked in both sequential and parallel case. In the sequential case it is invoked for the whole image; in the parallel case it is invoked for only one tile.

      This method may be invoked concurrently by many threads. Fields used by this method shall be thread-safe when not modified.

      Parameters:
      accumulator - where to accumulate the statistics results.
      it - the iterator on a raster or on the whole image.

    • computeSequentially

      protected Object computeSequentially()
      Computes the statistics on the image using a single thread. This is used for testing purposes, or when the image has only one tile, or when the implementation of RenderedImage.getTile(int, int) may be non thread-safe.
      Specified by:
      computeSequentially in class AnnotatedImage
      Returns:
      the computed property value. Note that null is a valid result.

    • cloneProperty

      protected Object cloneProperty(String name, Object value)
      Invoked when a property of the given name has been requested and that property is cached. The property should be cloned before to be returned to the user in order to protect this image state.
      Overrides:
      cloneProperty in class AnnotatedImage
      Parameters:
      name - the property name.
      value - the property value (never null).
      Returns:
      the property value to give to user.

    • collector

      protected Collector<Raster,Statistics[],Statistics[]> collector()
      Returns the function to execute for parallel computation of statistics, together with other required functions (supplier of accumulator, combiner, finisher).
      Overrides:
      collector in class AnnotatedImage
      Returns:
      functions for multi-threaded computation of property value, or null if unsupported.

    • createAccumulator

      private Statistics[] createAccumulator()
      Invoked for creating the object holding the information to be computed by a single thread. This method will be invoked for each worker thread before the worker starts its execution.
      Returns:
      a thread-local variable holding information computed by a single thread. May be null if such objects are not needed.

    • combine

      private static Statistics[] combine(Statistics[] previous, Statistics[] computed)
      Invoked after a thread finished to process all its tiles and wants to combine its result with the result of another thread. This method is invoked only if createAccumulator() returned a non-null value. This method does not need to be thread-safe; synchronizations will be done by the caller.
      Parameters:
      previous - the result of another thread (never null).
      computed - the result computed by current thread (never null).
      Returns:
      combination of the two results. May be one of the previous or computed instances.

    • compute

      private void compute(Statistics[] accumulator, Raster tile)
      Executes this operation on the given tile. This method may be invoked from any thread. If an exception occurs during computation, that exception will be logged or wrapped in an ImagingOpException by the caller.
      Parameters:
      accumulator - the thread-local variable created by createAccumulator().
      tile - the tile on which to perform a computation.
      Throws:
      RuntimeException - if the calculation failed.

    • filterNodataValues

      static DoubleUnaryOperator filterNodataValues(Number[] values)
      Builds an operator which can be used for filtering "no data" values. Calls to applyAsDouble(x) on the returned operator will return Double.NaN if the x value is equal to one of the given no-data values, and will return x unchanged otherwise. This operator can be used as a sampleFilters argument in calls to StatisticsCalculator(RenderedImage, Shape, DoubleUnaryOperator[], boolean, boolean).
      Parameters:
      values - the "no data" values. Null and NaN elements are ignored.
      Returns:
      an operator for filtering the given "no data" values, or null if there are no non-NaN values to filter.