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
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 Summary
FieldsModifier and TypeFieldDescriptionprivate final DoubleUnaryOperator[]
An optional function for converting values before to add them to statistics.Fields inherited from class org.apache.sis.image.AnnotatedImage
areaOfInterest, boundsOfInterest, WARNINGS_SUFFIX
Fields inherited from class org.apache.sis.image.ImageAdapter
source
Fields inherited from class org.apache.sis.image.PlanarImage
GRID_GEOMETRY_KEY, MASK_KEY, POSITIONAL_ACCURACY_KEY, SAMPLE_RESOLUTIONS_KEY, STATISTICS_KEY
-
Constructor Summary
ConstructorsConstructorDescriptionStatisticsCalculator
(RenderedImage image, Shape areaOfInterest, DoubleUnaryOperator[] sampleFilters, boolean parallel, boolean failOnException) Creates a new calculator. -
Method Summary
Modifier and TypeMethodDescriptionprotected Object
cloneProperty
(String name, Object value) Invoked when a property of the given name has been requested and that property is cached.protected Collector
<Raster, Statistics[], Statistics[]> Returns the function to execute for parallel computation of statistics, together with other required functions (supplier of accumulator, combiner, finisher).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.private void
compute
(DoubleConsumer[] accumulator, PixelIterator it) Computes statistics using the given iterator and accumulates the result for all bands.private void
compute
(Statistics[] accumulator, Raster tile) Executes this operation on the given tile.protected Object
Computes the statistics on the image using a single thread.private Statistics[]
Invoked for creating the object holding the information to be computed by a single thread.private static Statistics[]
createAccumulator
(int numBands) Creates the objects where to add sample values for computing statistics.private DoubleConsumer[]
filtered
(Statistics[] accumulator) Returns accumulators which will apply theinvalid reference
#filter
(package private) static DoubleUnaryOperator
filterNodataValues
(Number[] values) Builds an operator which can be used for filtering "no data" values.protected String
Returns the name of the property which is computed by this image.(package private) final Object[]
Returns the optional filter parameter.Methods inherited from class org.apache.sis.image.AnnotatedImage
appendStringContent, computeProperty, equals, getProperty, getPropertyNames, hashCode, logAndClearError, unique
Methods inherited from class org.apache.sis.image.ImageAdapter
copyData, getColorModel, getData, getData, getHeight, getMinTileX, getMinTileY, getMinX, getMinY, getNumXTiles, getNumYTiles, getSampleModel, getSources, getTile, getTileGridXOffset, getTileGridYOffset, getTileHeight, getTileWidth, getWidth, prefetch, toString
Methods inherited from class org.apache.sis.image.PlanarImage
getBounds, verify
-
Field Details
-
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, ornull
for the whole image.sampleFilters
- converters to apply on sample values before to add them to statistics, ornull
.parallel
- whether parallel execution is authorized.failOnException
- whether errors occurring during computation should be propagated.
-
-
Method Details
-
getExtraParameter
Returns the optional filter parameter. This is used by parent class for caching and forAnnotatedImage.equals(Object)
andAnnotatedImage.hashCode()
implementations.- Overrides:
getExtraParameter
in classAnnotatedImage
- Returns:
- subclass specific extra parameter, or
null
if none.
-
getComputedPropertyName
Returns the name of the property which is computed by this image.- Specified by:
getComputedPropertyName
in classAnnotatedImage
- Returns:
- name of property computed by this image. Shall not be null.
-
createAccumulator
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
Returns accumulators which will apply theinvalid reference
#filter
accumulator
array directly.- Parameters:
accumulator
- where to accumulate the statistics results.- Returns:
- the accumulator optionally filtered.
-
compute
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
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 ofRenderedImage.getTile(int, int)
may be non thread-safe.- Specified by:
computeSequentially
in classAnnotatedImage
- Returns:
- the computed property value. Note that
null
is a valid result.
-
cloneProperty
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 classAnnotatedImage
- Parameters:
name
- the property name.value
- the property value (nevernull
).- Returns:
- the property value to give to user.
-
collector
Returns the function to execute for parallel computation of statistics, together with other required functions (supplier of accumulator, combiner, finisher).- Overrides:
collector
in classAnnotatedImage
- Returns:
- functions for multi-threaded computation of property value, or
null
if unsupported.
-
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
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 ifcreateAccumulator()
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 (nevernull
).computed
- the result computed by current thread (nevernull
).- Returns:
- combination of the two results. May be one of the
previous
orcomputed
instances.
-
compute
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 anImagingOpException
by the caller.- Parameters:
accumulator
- the thread-local variable created bycreateAccumulator()
.tile
- the tile on which to perform a computation.- Throws:
RuntimeException
- if the calculation failed.
-
filterNodataValues
Builds an operator which can be used for filtering "no data" values. Calls toapplyAsDouble(x)
on the returned operator will returnDouble.NaN
if the x value is equal to one of the given no-datavalues
, and will return x unchanged otherwise. This operator can be used as asampleFilters
argument in calls toStatisticsCalculator(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.
-