Skip navigation links
AlgART Home
net.algart.matrices.morphology

## Interface RankMorphology

• All Superinterfaces:
ArrayProcessor, ArrayProcessorWithContextSwitching, Morphology
All Known Implementing Classes:
AbstractRankMorphology, BasicRankMorphology, ContinuedRankMorphology, TiledRankMorphology

```public interface RankMorphology
extends Morphology```

Rank operations over `n-dimensional matrices`: percentile, rank, mean between given percentiles or values, etc., calculated on all matrix elements in an aperture with the fixed shape, represented by `Pattern` class. It is supposed that the type of matrix elements is one of primitive Java types (boolean, char, byte, short, int, long, float, double) and, so, represents an integer or a real number, according to comments to `PFixedArray.getLong(long)` and `PArray.getDouble(long)` methods. In 2-dimensional case, these operations can be used for processing grayscale digital images.

The simplest rank operation is a percentile, for example, minimum, maximum or median. In the case of maximum, the percentile is strictly equivalent to dilation — the basic operation of the mathematical morphology, offered by `Morphology` interface. In the case of minimum, the percentile by some pattern P is equivalent to erosion by the symmetric pattern P.`symmetric()`. It allows to consider rank operations as an extension of the operation set of the traditional mathematical morphology. Really, this interface extends `Morphology` interface, and it is supposed, by definition, that `dilation`(m,pattern) method is equivalent to `percentile`(m,c*N,pattern) and `erosion`(m,pattern) method is equivalent to `percentile`(m,c*N,pattern.`symmetric()`), where N=pattern.`pointCount()`-1 and c is some constant, specified while instantiating this object (it is dilationLevel argument of `BasicRankMorphology.getInstance` method).

Below is the formal definition of 5 basic rank operations with the given pattern P and matrix M: percentile, rank, mean between 2 percentiles, mean between 2 ranks and aperture sum, calculated by this class.

1. For any integer point, or position x = (x0, x1, ..., xn−1), n=M.`dimCount()`, the aperture of this point, or the aperture at the position x, is a set of points xpi = (x0pi0, x1pi1, ..., xn−1pi,n−1) for all piP (`points` of the pattern P). We always consider that the point x lies inside M matrix (0≤xk<M.`dim`(k) for all k), but this condition can be not true for points of the aperture xpi.

2. For every point x' = xpi of the aperture we consider the corresponding value vi of the source matrix M. The precise definition of the value can depend on implementation of this interface. Usually, if the point lies inside the matrix (0≤xkpi,k<M.`dim`(k) for all k), it is the value of the element (integer: `PFixedArray.getLong(long)`, if the type of the matrix elements is boolean, char, byte, short, int or long, or real: `PArray.getDouble(long)`, if the element type is float or double) of the underlying array M.`array()` with an index M.`index`(x'0, x'1, ..., x'n−1), where x'k = xkpi,k. In particular, it is true for all implementations offered by this package. If the point x' = xpi lies outside the matrix (x'k<0 or x'kM.`dim`(k) for some k), then:
3. So, for every point x we have an aperture, consisting of N=P.`pointCount()` "neighbour" points xpi, and a corresponding set of integer or real values vi, i=0,1,...,N−1. Then we consider a histogram built on the base of vi values — the histogram, corresponding to the point x. Namely, this histogram is an array of non-negative integer numbers b[w], 0≤w<M, where every element b[w] represents the number of occurrence of the value w in array A, consisting of the following N integer elements a0, a1, ..., xN−1: In other words, the "standard" allowed range of element values 0..`Arrays.maxPossibleValue`(M.`elementType()`,1.0) is split into M=2μ histogram bars and all aperture values vi are distributed between these bars; elements, which are out of the allowed range, are distributed between the first and last bars. In the simplest case of byte elements, M is usually chosen to be 256; then σ=1.0 and ai = vi (because byte elements, in terms of AlgART libraries, cannot be out of 0..255 range).

4. The histogram b, b, ..., b[M−1], specified above, is interpreted in terms of `Histogram` and `SummingHistogram` classes. Namely, we define the following rank characteristics:
• the percentile with the given real index r is v(r)/σ, where v(r) function is defined in comments to `Histogram` class;
• the rank of the given real value v is r(v*σ), where r(v) function is defined in comments to `Histogram` class;
• the mean between 2 given percentiles with the real indexes r1 and r2 is (S(r2)−S(r1)) / ((r2r1)*σ) if r1<r2 or some reserved value filler if r1r2, where S(r) function is defined in comments to `SummingHistogram` class;
• the mean between 2 given values, the real numbers v1 and v2, is (s(v2*σ)−s(v1*σ)) / (r(v2*σ)−r(v1*σ))*σ) if v1<v2 and r(v1*σ)<r(v2*σ), where r(v) function is defined in comments to `Histogram` class and s(v) function is defined in comments to `SummingHistogram` class. If the conditions v1<v2 and r(v1*σ)<r(v2*σ) are not fulfilled, we use one of 4 following modes of calculation:
1. if any of these two conditions is not fulfilled, it is equal to some reserved value filler;
2. if any of these two conditions is not fulfilled, it is equal to v1;
3. if any of these two conditions is not fulfilled, it is equal to v2;
4. (most useful definition)
1. if v1v2, it is equal to (v1+v2)/2;
2. if v1<v2 and r(v2*σ)=r(v1*σ)=0, it is equal to v2 (see also `CountOfValues.isLeftBound()`);
3. if v1<v2 and r(v2*σ)=r(v1*σ)=N, it is equal to v1 (see also `CountOfValues.isRightBound()`);
4. in other cases, it is equal to (v1+v2)/2.
Remember that r(v) is always a non-decreasing function, so, the sentence "the conditions v1<v2 and r(v1*σ)<r(v2*σ) are not fulfilled" means, that either v1v2, or v1<v2 and r(v1*σ)=r(v2*σ). The last situation usually occurs "outside" the histogram, when both v1 and v2 values are less than (or equal to) the minimal value in the aperture or greater than (or equal to) the maximum value in the aperture. However, while using the simple histogram model, such situation is also possible on a sparse histogram with many zero bars;
• the aperture sum is just a usual sum of all values v0+v1+...+vN−1 — the only rank characteristic which does not use the histogram b[k]. (Of course, you can also calculate the mean of all values on the base of this sum: it is enough to divide the sum by N.)
Note 1: it is obvious that all rank characteristics, excepting the aperture sum, depend on the histogram model: simple or precise (see comments to `Histogram` and `SummingHistogram` classes). The used model is chosen while instantiating this class, usually via `CustomRankPrecision.interpolated()` flag in the argument of `CustomRankPrecision` class: true value ("interpolated") means the precise model, false means the simple one.
Note 2: for int, long, float and double element type of the source matrix M and for all characteristics, excepting the aperture sum, this definition supposes that all matrix elements lie in the "standard range": 0..Integer/Long.MAX_VALUE (all non-negative values) for integers or 0.0..1.0 for floating-point elements. If some matrix elements are negative, they are interpreted as 0; if some elements of a floating-point matrix are greater than 1.0, they are interpreted as 1.0. For floating-point case, the histogram length M actually specifies the precision of calculations: the source elements are represented with the precision 1/M. The aperture sum characteristic is an exception from this rule: aperture sums are calculated as usual sums of the source elements vi with double precision.
Note 3: for floating-point case, if the value of some element vi of the source matrix M inside the aperture is NaN (Float.NaN for float type, Double.NaN for double type), this situation does not lead to an exception, but the resulting values of all characteristics, listed above, are undocumented.
Note 4: unlike this, if some arguments of the characteristics, listed above — the real index r for the percentile, the real value v for the rank, the real indexes r1 and r2 for the mean between percentiles or the real values v1 and v2 for the mean between values — are NaN, then any attempt to calculate these characteristics by methods of this interface can lead to IllegalArgumentException.

This interface provides method for calculating the described 5 rank characteristics for every integer point x lying in the matrix M. The resulting characteristics are returned in the result matrix with the same dimensions as M. The necessary arguments — the real index r for the percentile, the real value v for the rank, the real indexes r1 and r2 for the mean between percentiles or the real values v1 and v2 for the mean between values — are retrieved from the corresponding element (with the index M.`index`(x0, x1, ..., xn−1)) of the `built-in array` of some additional matrix or pair of matrices, passed to the methods, by `PArray.getDouble(long)` method. It is supposed that those matrices have the same dimensions as M. For the percentile and the mean between percentiles, there are simplified versions of the methods, which use the constant rank indexes instead of matrices of indexes.

Most of methods of this interface allow to return not only floating-point, but also integer result matrix. In this case, the real rank characteristics, defined above in the section 4, are rounded by some rules, that are specified in comments to the concrete methods.

For every rank characteristics this interface offers 3 methods for calculating it. Below are some comments about them.

• The first version is always called "asOperation", for example, `asPercentile`. This method returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the necessary rank characteristic of the source matrix with the specified pattern (aperture shape). The result of such method is usually "lazy", that means that this method finishes immediately and all actual calculations are performed while getting elements of the returned matrix. It is true for all implementations provided by this package. However, some implementations may not support lazy execution; then the method may be equivalent to the second version described below. Note that the sequential access to the lazy result, returned by this method (via `Array.getData` method, called for the `built-in array` of the returned matrix), usually works much faster than the random access to elements of the matrix.
• The second version is called "operation", for example, `percentile`. This method always returns actual (non-lazy) updatable result: Matrix<? extends UpdatablePArray>. This method can work essentially faster than an access to the lazy matrix returned by the first variant of the method (for example, than copying it into a new matrix). In implementations, offered by this package, there are no difference if the source matrix src (for rank operations, baseMatrix) is direct accessible: src.`array()` instanceof `DirectAccessible` && ((DirectAccessible)src.`array()`).`hasJavaArray()`. If the source matrix is not direct accessible, the implementations, offered by this package, use `StreamingApertureProcessor` technique to accelerate processing. Calculating aperture sums is an exception: `functionOfSum` method uses some optimization for some kinds of patterns and can work much faster than accessing to `asFunctionOfSum` result.
• The third version is also called "operation", but it is a void method: for example, `percentile(Matrix, Matrix, Matrix, Pattern)`. The result matrix is passed via first argument named dest and supposed to be allocated before calling the method. This way allows to save memory and time, if you need to perform several rank operation, because you can use the same matrices for temporary results. In addition, these methods allow to choose the type of element of the resulting matrix for any operation. The precise rules of type conversions are described in comments to concrete methods.

This package provides the following basic methods for creating objects, implementing this interface:

Warning: all implementations of this interface, provided by this package, can process only patterns where `pointCount()`≤Integer.MAX_VALUE. More precisely, any methods of this interface (including methods, inherited from its superinterface `Morphology`), implemented by classes of this package, which have `Pattern` argument, can throw `TooManyPointsInPatternError` or OutOfMemoryError in the same situations as `Pattern.points()` method.

Warning: the methods of this interface, which save results into the passed dest matrix (like `percentile(Matrix, Matrix, Matrix, Pattern)`), as well as any attempts to read the "lazy" results (of the methods like `asPercentile(Matrix, Matrix, Pattern)`), can be non-atomic regarding the failure, if the arguments of the calculated rank characteristics — the real index r for the percentile, the real value v for the rank, the real indexes r1 and r2 for the mean between percentiles or the real values v1 and v2 for the mean between values — are floating-point NaN values for some aperture positions. In this case, it is possible that the result will be partially filled, and only after this the NaN value will lead to IllegalArgumentException.

The floating-point calculations in the implementations of this interface are usually performed not in strictfp, but in the usual mode. So, there is no guarantee that the results are absolutely identical on all platforms. Moreover, there is no guarantee that the same results, got by different ways, are absolutely identical: little mismatches in the last digits after the decimal point are possible.

The classes, implementing this interface, are immutable and thread-safe: there are no ways to modify settings of the created instance.

Since:
JDK 1.5
Version:
1.2
Author:
Daniel Alievsky

• ### Nested classes/interfaces inherited from interface net.algart.matrices.morphology.Morphology

`Morphology.SubtractionMode`
• ### Field Summary

Fields
Modifier and Type Field and Description
`static double` `FILL_MAX_VALUE`
Special value of filler argument of methods, calculating mean between 2 values, which activates the mode C of calculation: if r(v1*σ)≥r(v2*σ), the mean is considered to be equal v2.
`static double` `FILL_MIN_VALUE`
Special value of filler argument of methods, calculating mean between 2 values, which activates the mode B of calculation: if r(v1*σ)≥r(v2*σ), the mean is considered to be equal v1.
`static double` `FILL_NEAREST_VALUE`
Special value of filler argument of methods, calculating mean between 2 values, which activates the mode D of calculation.
• ### Method Summary

All Methods
Modifier and Type Method and Description
`Matrix<? extends PArray>` ```asFunctionOfPercentilePair(Matrix<? extends PArray> src, double percentileIndex1, double percentileIndex2, Pattern pattern, Func processingFunc)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the result of some given function f(v, v1,v2) of the source matrix v and two percentiles v1,v2 of the source matrix by the specified pattern.
`Matrix<? extends PArray>` ```asFunctionOfPercentilePair(Matrix<? extends PArray> src, Matrix<? extends PArray> percentileIndexes1, Matrix<? extends PArray> percentileIndexes2, Pattern pattern, Func processingFunc)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the result of some given function f(v, v1,v2) of the source matrix v and two percentiles v1,v2 of the source matrix by the specified pattern.
`Matrix<? extends PArray>` ```asFunctionOfSum(Matrix<? extends PArray> src, Pattern pattern, Func processingFunc)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the result of some given function f(S) of the aperture sum S of the source matrix by the specified pattern.
`Matrix<? extends PArray>` ```asMean(Matrix<? extends PArray> src, Pattern pattern)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the mean of the source matrix by the specified pattern.
`Matrix<? extends PArray>` ```asMeanBetweenPercentiles(Matrix<? extends PArray> src, double fromPercentileIndex, double toPercentileIndex, Pattern pattern, double filler)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the mean between 2 percentiles of the source matrix by the specified pattern.
`Matrix<? extends PArray>` ```asMeanBetweenPercentiles(Matrix<? extends PArray> src, Matrix<? extends PArray> fromPercentileIndexes, Matrix<? extends PArray> toPercentileIndexes, Pattern pattern, double filler)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the mean between 2 percentiles of the source matrix by the specified pattern.
`Matrix<? extends PArray>` ```asMeanBetweenValues(Matrix<? extends PArray> src, Matrix<? extends PArray> minValues, Matrix<? extends PArray> maxValues, Pattern pattern, double filler)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the mean between 2 values of the source matrix by the specified pattern.
`Matrix<? extends PArray>` ```asPercentile(Matrix<? extends PArray> src, double percentileIndex, Pattern pattern)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the percentile of the source matrix by the specified pattern.
`Matrix<? extends PArray>` ```asPercentile(Matrix<? extends PArray> src, Matrix<? extends PArray> percentileIndexes, Pattern pattern)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the percentile of the source matrix by the specified pattern.
`<T extends PArray>Matrix<T>` ```asRank(java.lang.Class<? extends T> requiredType, Matrix<? extends PArray> baseMatrix, Matrix<? extends PArray> rankedMatrix, Pattern pattern)```
Returns an immutable view of the passed baseMatrix matrix, such that any reading data from it calculates and returns the ranks of some given values v regarding the source matrix baseMatrix with the specified pattern.
`RankMorphology` `context(ArrayContext newContext)`
Switches the context: returns an instance, identical to this one excepting that it uses the specified newContext for all operations.
`Matrix<? extends UpdatablePArray>` ```functionOfPercentilePair(Matrix<? extends PArray> src, double percentileIndex1, double percentileIndex2, Pattern pattern, Func processingFunc)```
Returns a new updatable matrix, containing the result of some given function f(v, v1,v2) of the source matrix v and two percentiles v1,v2 of the source matrix by the specified pattern.
`Matrix<? extends UpdatablePArray>` ```functionOfPercentilePair(Matrix<? extends PArray> src, Matrix<? extends PArray> percentileIndexes1, Matrix<? extends PArray> percentileIndexes2, Pattern pattern, Func processingFunc)```
Returns a new updatable matrix, containing the result of some given function f(v, v1,v2) of the source matrix v and two percentiles v1,v2 of the source matrix by the specified pattern.
`void` ```functionOfPercentilePair(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, double percentileIndex1, double percentileIndex2, Pattern pattern, Func processingFunc)```
Equivalent to `functionOfPercentilePair(Matrix, double, double, Pattern, Func)` method, but the result matrix will be placed in the dest argument.
`void` ```functionOfPercentilePair(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Matrix<? extends PArray> percentileIndexes1, Matrix<? extends PArray> percentileIndexes2, Pattern pattern, Func processingFunc)```
Equivalent to `functionOfPercentilePair(Matrix, Matrix, Matrix, Pattern, Func)` method, but the result matrix will be placed in the dest argument.
`Matrix<? extends UpdatablePArray>` ```functionOfSum(Matrix<? extends PArray> src, Pattern pattern, Func processingFunc)```
Returns a new updatable matrix, containing the result of some given function f(S) of the aperture sum S of the source matrix by the specified pattern.
`void` ```functionOfSum(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Pattern pattern, Func processingFunc)```
Equivalent to `functionOfSum(Matrix, Pattern, Func)` method, but the result matrix will be placed in the dest argument.
`Matrix<? extends UpdatablePArray>` ```mean(Matrix<? extends PArray> src, Pattern pattern)```
Returns a new updatable matrix, containing the mean of the source matrix by the specified pattern.
`void` ```mean(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Pattern pattern)```
Equivalent to `mean(Matrix, Pattern)` method, but the result matrix will be placed in the dest argument.
`Matrix<? extends UpdatablePArray>` ```meanBetweenPercentiles(Matrix<? extends PArray> src, double fromPercentileIndex, double toPercentileIndex, Pattern pattern, double filler)```
Returns a new updatable matrix, containing the mean between 2 percentiles of the source matrix by the specified pattern.
`Matrix<? extends UpdatablePArray>` ```meanBetweenPercentiles(Matrix<? extends PArray> src, Matrix<? extends PArray> fromPercentileIndexes, Matrix<? extends PArray> toPercentileIndexes, Pattern pattern, double filler)```
Returns a new updatable matrix, containing the mean between 2 percentiles of the source matrix by the specified pattern.
`void` ```meanBetweenPercentiles(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, double fromPercentileIndex, double toPercentileIndex, Pattern pattern, double filler)```
Equivalent to `meanBetweenPercentiles(Matrix, double, double, Pattern, double)` method, but the result matrix will be placed in the dest argument.
`void` ```meanBetweenPercentiles(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Matrix<? extends PArray> fromPercentileIndexes, Matrix<? extends PArray> toPercentileIndexes, Pattern pattern, double filler)```
Equivalent to `meanBetweenPercentiles(Matrix, Matrix, Matrix, Pattern, double)` method, but the result matrix will be placed in the dest argument.
`Matrix<? extends UpdatablePArray>` ```meanBetweenValues(Matrix<? extends PArray> src, Matrix<? extends PArray> minValues, Matrix<? extends PArray> maxValues, Pattern pattern, double filler)```
Returns a new updatable matrix, containing the mean between 2 values of the source matrix by the specified pattern.
`void` ```meanBetweenValues(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Matrix<? extends PArray> minValues, Matrix<? extends PArray> maxValues, Pattern pattern, double filler)```
Equivalent to `meanBetweenValues(Matrix, Matrix, Matrix, Pattern, double)` method, but the result matrix will be placed in the dest argument.
`Matrix<? extends UpdatablePArray>` ```percentile(Matrix<? extends PArray> src, double percentileIndex, Pattern pattern)```
Returns a new updatable matrix, containing the percentile of the source matrix by the specified pattern.
`Matrix<? extends UpdatablePArray>` ```percentile(Matrix<? extends PArray> src, Matrix<? extends PArray> percentileIndexes, Pattern pattern)```
Returns a new updatable matrix, containing the percentile of the source matrix by the specified pattern.
`void` ```percentile(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, double percentileIndex, Pattern pattern)```
Equivalent to `percentile(Matrix, double, Pattern)` method, but the result matrix will be placed in the dest argument.
`void` ```percentile(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Matrix<? extends PArray> percentileIndexes, Pattern pattern)```
Equivalent to `percentile(Matrix, Matrix, Pattern)` method, but the result matrix will be placed in the dest argument.
`<T extends PArray>Matrix<? extends T>` ```rank(java.lang.Class<? extends T> requiredType, Matrix<? extends PArray> baseMatrix, Matrix<? extends PArray> rankedMatrix, Pattern pattern)```
Returns a new updatable matrix, containing the rank of some given values v regarding the source matrix baseMatrix with the specified pattern.
`void` ```rank(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> baseMatrix, Matrix<? extends PArray> rankedMatrix, Pattern pattern)```
Equivalent to `rank(Class, Matrix, Matrix, Pattern)` method, but the result matrix will be placed in the dest argument and the required type will be chosen automatically as dest.`type`(PArray.class).
• ### Methods inherited from interface net.algart.matrices.morphology.Morphology

`asDilation, asErosion, beucherGradient, closing, dilation, dilation, dilation, dilation, dilationErosion, erosion, erosion, erosion, erosion, erosionDilation, isPseudoCyclic, maskedDilationErosion, maskedErosionDilation, opening, weakDilation, weakErosion`
• ### Methods inherited from interface net.algart.arrays.ArrayProcessor

`context`
• ### Field Detail

• #### FILL_MIN_VALUE

`static final double FILL_MIN_VALUE`
Special value of filler argument of methods, calculating mean between 2 values, which activates the mode B of calculation: if r(v1*σ)≥r(v2*σ), the mean is considered to be equal v1. See the `comments to this class`, section 4 about the "mean between 2 values" term.

This constant contains Double.NEGATIVE_INFINITY value, which is usually useless in a role of the ordinary filler for the mode A of calculations.

See Also:
Constant Field Values
• #### FILL_MAX_VALUE

`static final double FILL_MAX_VALUE`
Special value of filler argument of methods, calculating mean between 2 values, which activates the mode C of calculation: if r(v1*σ)≥r(v2*σ), the mean is considered to be equal v2. See the `comments to this class`, section 4 about the "mean between 2 values" term.

This constant contains Double.POSITIVE_INFINITY value, which is usually useless in a role of the ordinary filler for the mode A of calculations.

See Also:
Constant Field Values
• #### FILL_NEAREST_VALUE

`static final double FILL_NEAREST_VALUE`
Special value of filler argument of methods, calculating mean between 2 values, which activates the mode D of calculation. In this case:
1. if v1v2, the mean is considered to be equal to (v1+v2)/2;
2. if v1<v2 and r(v2*σ)=r(v1*σ)=0, the mean is considered to be equal to v2 (see also `CountOfValues.isLeftBound()`);
3. if v1<v2 and r(v2*σ)=r(v1*σ)=N, the mean is considered to be equal to v1 (see also `CountOfValues.isRightBound()`);
4. in other cases, if r(v1*σ)=r(v2*σ), the mean is considered to be equal to (v1+v2)/2.
See the `comments to this class`, section 4 about the "mean between 2 values" term.

This constant contains Double.NaN value, which is usually useless in a role of the ordinary filler for the mode A of calculations.

Warning: because this constant is Double.NaN, according to rules of Java language, you must not compare any numbers with this constant! A check like

``` if (x == RankMorphology.FILL_NEAREST_VALUE) {
...
}
```
always returns false. You should use Double.isNaN(x) call instead.
See Also:
Constant Field Values
• ### Method Detail

• #### context

`RankMorphology context(ArrayContext newContext)`
Description copied from interface: `ArrayProcessorWithContextSwitching`
Switches the context: returns an instance, identical to this one excepting that it uses the specified newContext for all operations. The returned instance is usually a clone of this one, but there is no guarantees that it is a deep clone. Usually, the returned instance is used only for performing a `subtask` of the full task.
Specified by:
`context` in interface `ArrayProcessorWithContextSwitching`
Specified by:
`context` in interface `Morphology`
Parameters:
`newContext` - another context, used by the returned instance; may be null.
Returns:
new instance with another context.
• #### asPercentile

```Matrix<? extends PArray> asPercentile(Matrix<? extends PArray> src,
Matrix<? extends PArray> percentileIndexes,
Pattern pattern)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the percentile of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "percentile" term. The real index r of the percentile for every element of the result is equal to the corresponding element of percentileIndexes matrix. The `element type` of the created matrix is the same as the element type of the source one.

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real percentile v(r)/σ, defined in the comments to this class. In this case, this method, instead of the real value v(r)/σ, returns an integer w, where w is:

It is necessary to remind: in a case of fixed-point elements there is a guarantee that 1/σ is a positive integer number, and w/σ=w*2β−μ, β = src.`array()`.`bitsPerElement()`, μ is the binary logarithm of the histogram length M — see the `comments to this class`, section 3. So, if μ is chosen less than the precision of this matrix β (8 for byte, 16 for short, etc.), then β−μ lowest bits in the result will be always zero. For `BasicRankMorphology` object, μ is chosen while `instantiating this object` as min(bitLevels[bitLevels.length-1], β).
Parameters:
`src` - the source matrix.
`percentileIndexes` - the matrix containing r argument: the indexes of the percentile for every element of the result.
`pattern` - the pattern: the shape of the aperture.
Returns:
the "lazy" matrix containing the percentile of the source matrix.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`asPercentile(Matrix, double, Pattern)`, `percentile(Matrix, Matrix, Pattern)`, `percentile(Matrix, Matrix, Matrix, Pattern)`
• #### asPercentile

```Matrix<? extends PArray> asPercentile(Matrix<? extends PArray> src,
double percentileIndex,
Pattern pattern)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the percentile of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "percentile" term. The real index r of the percentile is equal to percentileIndex argument for all aperture positions. The `element type` of the created matrix is the same as the element type of the source one.

This method is equivalent to

``asPercentile`(src, src.matrix(`Arrays.nDoubleCopies`(src.size(), percentileIndex), pattern)`

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real percentile v(r)/σ, defined in the comments to this class. In this case, this method, instead of the real value v(r)/σ, returns an integer w, where w is:

It is necessary to remind: in a case of fixed-point elements there is a guarantee that 1/σ is a positive integer number, and w/σ=w*2β−μ, β = src.`array()`.`bitsPerElement()`, μ is the binary logarithm of the histogram length M — see the `comments to this class`, section 3. So, if μ is chosen less than the precision of this matrix β (8 for byte, 16 for short, etc.), then β−μ lowest bits in the result will be always zero. For `BasicRankMorphology` object, μ is chosen while `instantiating this object` as min(bitLevels[bitLevels.length-1], β).
Parameters:
`src` - the source matrix.
`percentileIndex` - r argument of the percentile.
`pattern` - the pattern: the shape of the aperture.
Returns:
the "lazy" matrix containing the percentile of the source matrix.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`asPercentile(Matrix, Matrix, Pattern)`, `percentile(Matrix, double, Pattern)`, `percentile(Matrix, Matrix, double, Pattern)`
• #### percentile

```Matrix<? extends UpdatablePArray> percentile(Matrix<? extends PArray> src,
Matrix<? extends PArray> percentileIndexes,
Pattern pattern)```
Returns a new updatable matrix, containing the percentile of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "percentile" term. The real index r of the percentile for every element of the result is equal to the corresponding element of percentileIndexes matrix. The `element type` of the created matrix is the same as the element type of the source one.

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real percentile v(r)/σ, defined in the comments to this class. In this case, this method, instead of the real value v(r)/σ, returns an integer w, where w is:

It is necessary to remind: in a case of fixed-point elements there is a guarantee that 1/σ is a positive integer number, and w/σ=w*2β−μ, β = src.`array()`.`bitsPerElement()`, μ is the binary logarithm of the histogram length M — see the `comments to this class`, section 3. So, if μ is chosen less than the precision of this matrix β (8 for byte, 16 for short, etc.), then β−μ lowest bits in the result will be always zero. For `BasicRankMorphology` object, μ is chosen while `instantiating this object` as min(bitLevels[bitLevels.length-1], β).
Parameters:
`src` - the source matrix.
`percentileIndexes` - the matrix containing r argument: the indexes of the percentile for every element of the result.
`pattern` - the pattern: the shape of the aperture.
Returns:
the percentile of the source matrix.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`percentile(Matrix, double, Pattern)`, `asPercentile(Matrix, Matrix, Pattern)`, `percentile(Matrix, Matrix, Matrix, Pattern)`
• #### percentile

```Matrix<? extends UpdatablePArray> percentile(Matrix<? extends PArray> src,
double percentileIndex,
Pattern pattern)```
Returns a new updatable matrix, containing the percentile of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "percentile" term. The real index r of the percentile is equal to percentileIndex argument for all aperture positions. The `element type` of the created matrix is the same as the element type of the source one.

This method is equivalent to

``percentile`(src, src.matrix(`Arrays.nDoubleCopies`(src.size(), percentileIndex), pattern)`

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real percentile v(r)/σ, defined in the comments to this class. In this case, this method, instead of the real value v(r)/σ, returns an integer w, where w is:

It is necessary to remind: in a case of fixed-point elements there is a guarantee that 1/σ is a positive integer number, and w/σ=w*2β−μ, β = src.`array()`.`bitsPerElement()`, μ is the binary logarithm of the histogram length M — see the `comments to this class`, section 3. So, if μ is chosen less than the precision of this matrix β (8 for byte, 16 for short, etc.), then β−μ lowest bits in the result will be always zero. For `BasicRankMorphology` object, μ is chosen while `instantiating this object` as min(bitLevels[bitLevels.length-1], β).
Parameters:
`src` - the source matrix.
`percentileIndex` - r argument of the percentile.
`pattern` - the pattern: the shape of the aperture.
Returns:
the percentile of the source matrix.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`percentile(Matrix, Matrix, Pattern)`, `asPercentile(Matrix, double, Pattern)`, `percentile(Matrix, Matrix, double, Pattern)`
• #### asRank

```<T extends PArray> Matrix<T> asRank(java.lang.Class<? extends T> requiredType,
Matrix<? extends PArray> baseMatrix,
Matrix<? extends PArray> rankedMatrix,
Pattern pattern)```
Returns an immutable view of the passed baseMatrix matrix, such that any reading data from it calculates and returns the ranks of some given values v regarding the source matrix baseMatrix with the specified pattern. See the `comments to this class`, section 4 about the "rank" term. The real value v for every element of the result is equal to the corresponding element of rankedMatrix matrix.

The matrix, returned by this method, is immutable, and the class of its built-in array implements one of the basic interfaces `BitArray`, `CharArray`, `ByteArray`, `ShortArray`, `IntArray`, `LongArray`, `FloatArray` or `DoubleArray`. The class of desired interface (one of 8 possible classes) must be passed as requiredType argument. So, it defines the element type of the returned matrix. The rules of casting the floating-point ranks to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

The element types of baseMatrix and rankedMatrix are usually equal. If they are different (baseMatrix.`elementType()`!=rankedMatrix.`elementType()`), this method replaces rankedMatrix with

``Matrices.asFuncMatrix`(true, `Func.IDENTITY`, baseMatrix.array().`type()`, rankedMatrix)`

before all other calculations. In other words, this method always casts the type of the ranked elements to the type of baseMatrix elements. As a result, we can be sure, that if the source baseMatrix matrix is fixed-point (boolean, char, byte, short, int or long elements), then the rank r(v*σ), according to the definition of the "rank" term, will be an integer number. In this case, you can specify requiredType=IntArray.class and get the precise rank without precision loss. Moreover, if you know that the number of points in the pattern (pattern.`pointCount()`) is less than 216=65536 or 28=256, it is enough to specify correspondingly requiredType=ShortArray.class or ByteArray.class.

Parameters:
`requiredType` - the desired type of the built-in array in the returned matrix.
`baseMatrix` - the source matrix.
`rankedMatrix` - the matrix containing v argument: the values, the rank of which should be calculated.
`pattern` - the pattern: the shape of the aperture.
Returns:
the "lazy" matrix containing the rank of the given values.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to baseMatrix.`dimCount()`, or if requiredType is not one of classes `BitArray`.class, `CharArray`.class, `ByteArray`.class, `ShortArray`.class, `IntArray`.class, `LongArray`.class, `FloatArray`.class or `DoubleArray`.class.
See Also:
`rank(Class, Matrix, Matrix, Pattern)`, `rank(Matrix, Matrix, Matrix, Pattern)`
• #### rank

```void rank(Matrix<? extends UpdatablePArray> dest,
Matrix<? extends PArray> baseMatrix,
Matrix<? extends PArray> rankedMatrix,
Pattern pattern)```
Equivalent to `rank(Class, Matrix, Matrix, Pattern)` method, but the result matrix will be placed in the dest argument and the required type will be chosen automatically as dest.`type`(PArray.class). More precisely, the result, saved in dest, will be equal to
``rank`(dest.array().`type()`, baseMatrix, rankedMatrix, pattern)`

The element types of baseMatrix and rankedMatrix are usually equal. If they are different (baseMatrix.`elementType()`!=rankedMatrix.`elementType()`), this method replaces rankedMatrix with

``Matrices.asFuncMatrix`(true, `Func.IDENTITY`, baseMatrix.array().`type()`, rankedMatrix)`

before all other calculations. In other words, this method always casts the type of the ranked elements to the type of baseMatrix elements. As a result, we can be sure, that if the source baseMatrix matrix is fixed-point (boolean, char, byte, short, int or long elements), then the rank r(v*σ), according to the definition of the "rank" term, will be an integer number. In this case, you can specify requiredType=IntArray.class and get the precise rank without precision loss. Moreover, if you know that the number of points in the pattern (pattern.`pointCount()`) is less than 216=65536 or 28=256, it is enough to specify correspondingly requiredType=ShortArray.class or ByteArray.class. The less result precision allows you to save memory.

Parameters:
`dest` - the target matrix.
`baseMatrix` - the source matrix.
`rankedMatrix` - the matrix containing v argument: the values, the rank of which should be calculated.
`pattern` - the pattern: the shape of the aperture.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to baseMatrix.`dimCount()`.
See Also:
`asRank(Class, Matrix, Matrix, Pattern)`, `rank(Class, Matrix, Matrix, Pattern)`
• #### asMeanBetweenPercentiles

```Matrix<? extends PArray> asMeanBetweenPercentiles(Matrix<? extends PArray> src,
Matrix<? extends PArray> fromPercentileIndexes,
Matrix<? extends PArray> toPercentileIndexes,
Pattern pattern,
double filler)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the mean between 2 percentiles of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "mean between 2 percentiles" term. The real indexes r1 and r2 of the percentiles for every element of the result are equal to the corresponding elements of fromPercentileIndexes and toPercentileIndexes matrices. The reserved value filler is specified by the last argument of this method. The `element type` of the created matrix is the same as the element type of the source one.

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real mean, defined in the comments to this class. In this case, the found mean value m is usually truncated to its integer part m⌋=(long)m (remember that the mean value, according to our definition, is always ≥0). More precisely, the rules of casting the floating-point means to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

Parameters:
`src` - the source matrix.
`fromPercentileIndexes` - the matrix containing r1 argument: the indexes of the less percentile of the averaged range for every element of the result.
`toPercentileIndexes` - the matrix containing r2 argument: the indexes of the greater percentile of the averaged range for every element of the result.
`pattern` - the pattern: the shape of the aperture.
`filler` - the reserved value, returned when r1r2.
Returns:
the "lazy" matrix containing the mean between 2 given percentiles of the source matrix.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`asMeanBetweenPercentiles(Matrix, double, double, Pattern, double)`, `meanBetweenPercentiles(Matrix, Matrix, Matrix, Pattern, double)`, `meanBetweenPercentiles(Matrix, Matrix, Matrix, Matrix, Pattern, double)`
• #### asMeanBetweenPercentiles

```Matrix<? extends PArray> asMeanBetweenPercentiles(Matrix<? extends PArray> src,
double fromPercentileIndex,
double toPercentileIndex,
Pattern pattern,
double filler)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the mean between 2 percentiles of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "mean between 2 percentiles" term. The real indexes r1 and r2 of the percentiles for every element of the result are equal to fromPercentileIndex and toPercentileIndex arguments for all aperture positions. The reserved value filler is specified by the last argument of this method. The `element type` of the created matrix is the same as the element type of the source one.

This method is equivalent to

````asMeanBetweenPercentiles`(src,
src.matrix(`Arrays.nDoubleCopies`(src.size(), fromPercentileIndex),
src.matrix(`Arrays.nDoubleCopies`(src.size(), toPercentileIndex),
pattern, filler)```

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real mean, defined in the comments to this class. In this case, the found mean value m is usually truncated to its integer part m⌋=(long)m (remember that the mean value, according to our definition, is always ≥0). More precisely, the rules of casting the floating-point means to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

Parameters:
`src` - the source matrix.
`fromPercentileIndex` - r1 argument: the index of the less percentile of the averaged range for every element of the result.
`toPercentileIndex` - r2 argument: the indexes of the greater percentile of the averaged range for every element of the result.
`pattern` - the pattern: the shape of the aperture.
`filler` - the reserved value, returned when r1r2.
Returns:
the "lazy" matrix containing the mean between 2 given percentiles of the source matrix.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`asMeanBetweenPercentiles(Matrix, Matrix, Matrix, Pattern, double)`, `meanBetweenPercentiles(Matrix, double, double, Pattern, double)`, `meanBetweenPercentiles(Matrix, Matrix, double, double, Pattern, double)`
• #### meanBetweenPercentiles

```Matrix<? extends UpdatablePArray> meanBetweenPercentiles(Matrix<? extends PArray> src,
Matrix<? extends PArray> fromPercentileIndexes,
Matrix<? extends PArray> toPercentileIndexes,
Pattern pattern,
double filler)```
Returns a new updatable matrix, containing the mean between 2 percentiles of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "mean between 2 percentiles" term. The real indexes r1 and r2 of the percentiles for every element of the result are equal to the corresponding elements of fromPercentileIndexes and toPercentileIndexes matrices. The reserved value filler is specified by the last argument of this method. The `element type` of the created matrix is the same as the element type of the source one.

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real mean, defined in the comments to this class. In this case, the found mean value m is usually truncated to its integer part m⌋=(long)m (remember that the mean value, according to our definition, is always ≥0). More precisely, the rules of casting the floating-point means to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

Parameters:
`src` - the source matrix.
`fromPercentileIndexes` - the matrix containing r1 argument: the indexes of the less percentile of the averaged range for every element of the result.
`toPercentileIndexes` - the matrix containing r2 argument: the indexes of the greater percentile of the averaged range for every element of the result.
`pattern` - the pattern: the shape of the aperture.
`filler` - the reserved value, returned when r1r2.
Returns:
the mean between 2 given percentiles of the source matrix.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`meanBetweenPercentiles(Matrix, double, double, Pattern, double)`, `asMeanBetweenPercentiles(Matrix, Matrix, Matrix, Pattern, double)`, `meanBetweenPercentiles(Matrix, Matrix, Matrix, Matrix, Pattern, double)`
• #### meanBetweenPercentiles

```Matrix<? extends UpdatablePArray> meanBetweenPercentiles(Matrix<? extends PArray> src,
double fromPercentileIndex,
double toPercentileIndex,
Pattern pattern,
double filler)```
Returns a new updatable matrix, containing the mean between 2 percentiles of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "mean between 2 percentiles" term. The real indexes r1 and r2 of the percentiles for every element of the result are equal to fromPercentileIndex and toPercentileIndex arguments for all aperture positions. The reserved value filler is specified by the last argument of this method. The `element type` of the created matrix is the same as the element type of the source one.

This method is equivalent to

````meanBetweenPercentiles`(src,
src.matrix(`Arrays.nDoubleCopies`(src.size(), fromPercentileIndex),
src.matrix(`Arrays.nDoubleCopies`(src.size(), toPercentileIndex),
pattern, filler)```

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real mean, defined in the comments to this class. In this case, the found mean value m is usually truncated to its integer part m⌋=(long)m (remember that the mean value, according to our definition, is always ≥0). More precisely, the rules of casting the floating-point means to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

Parameters:
`src` - the source matrix.
`fromPercentileIndex` - r1 argument: the index of the less percentile of the averaged range for every element of the result.
`toPercentileIndex` - r2 argument: the indexes of the greater percentile of the averaged range for every element of the result.
`pattern` - the pattern: the shape of the aperture.
`filler` - the reserved value, returned when r1r2.
Returns:
the mean between 2 given percentiles of the source matrix.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`meanBetweenPercentiles(Matrix, Matrix, Matrix, Pattern, double)`, `asMeanBetweenPercentiles(Matrix, double, double, Pattern, double)`, `meanBetweenPercentiles(Matrix, Matrix, double, double, Pattern, double)`
• #### meanBetweenPercentiles

```void meanBetweenPercentiles(Matrix<? extends UpdatablePArray> dest,
Matrix<? extends PArray> src,
Matrix<? extends PArray> fromPercentileIndexes,
Matrix<? extends PArray> toPercentileIndexes,
Pattern pattern,
double filler)```
Equivalent to `meanBetweenPercentiles(Matrix, Matrix, Matrix, Pattern, double)` method, but the result matrix will be placed in the dest argument.

If the element type of dest matrix is fixed-point — boolean, char, byte, short, int or long — then we need to round the real mean, defined in the comments to this class. In this case, the found mean value m is usually truncated to its integer part m⌋=(long)m (remember that the mean value, according to our definition, is always ≥0). More precisely, the rules of casting the floating-point means to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

Parameters:
`dest` - the target matrix.
`src` - the source matrix.
`fromPercentileIndexes` - the matrix containing r1 argument: the indexes of the less percentile of the averaged range for every element of the result.
`toPercentileIndexes` - the matrix containing r2 argument: the indexes of the greater percentile of the averaged range for every element of the result.
`pattern` - the pattern: the shape of the aperture.
`filler` - the reserved value, returned when r1r2.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`meanBetweenPercentiles(Matrix, Matrix, double, double, Pattern, double)`, `asMeanBetweenPercentiles(Matrix, Matrix, Matrix, Pattern, double)`, `meanBetweenPercentiles(Matrix, Matrix, Matrix, Pattern, double)`
• #### asMeanBetweenValues

```Matrix<? extends PArray> asMeanBetweenValues(Matrix<? extends PArray> src,
Matrix<? extends PArray> minValues,
Matrix<? extends PArray> maxValues,
Pattern pattern,
double filler)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the mean between 2 values of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "mean between 2 values" term. The real numbers v1 and v2 for every element of the result are equal to the corresponding elements of minValues and maxValues matrices. The reserved value filler and the mode of calculation (for the case r(v1*σ)≥r(v2*σ)) are specified by the last filler argument of this method: The `element type` of the created matrix is the same as the element type of the source one.

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real mean, defined in the comments to this class. In this case, the found mean value m is usually truncated to its integer part m⌋=(long)m (remember that the mean value, according to our definition, is always ≥0). More precisely, the rules of casting the floating-point means to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

Parameters:
`src` - the source matrix.
`minValues` - the matrix containing v1 argument: the low bound of the averaged range of values for every element of the result.
`maxValues` - the matrix containing v2 argument: the high bound of the averaged range of values for every element of the result.
`pattern` - the pattern: the shape of the aperture.
`filler` - the reserved value, returned when r(v1*σ)≥r(v2*σ), or one of the special keys `FILL_MIN_VALUE`, `FILL_MAX_VALUE`, `FILL_NEAREST_VALUE`, which mean using of special calculation modes B, C, D.
Returns:
the "lazy" matrix containing the mean between 2 given values of the source matrix.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`meanBetweenValues(Matrix, Matrix, Matrix, Pattern, double)`, `meanBetweenValues(Matrix, Matrix, Matrix, Matrix, Pattern, double)`
• #### meanBetweenValues

```Matrix<? extends UpdatablePArray> meanBetweenValues(Matrix<? extends PArray> src,
Matrix<? extends PArray> minValues,
Matrix<? extends PArray> maxValues,
Pattern pattern,
double filler)```
Returns a new updatable matrix, containing the mean between 2 values of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "mean between 2 values" term. The real numbers v1 and v2 for every element of the result are equal to the corresponding elements of minValues and maxValues matrices. The reserved value filler and the mode of calculation (for the case r(v1*σ)≥r(v2*σ)) are specified by the last filler argument of this method: The `element type` of the created matrix is the same as the element type of the source one.

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real mean, defined in the comments to this class. In this case, the found mean value m is usually truncated to its integer part m⌋=(long)m (remember that the mean value, according to our definition, is always ≥0). More precisely, the rules of casting the floating-point means to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

Parameters:
`src` - the source matrix.
`minValues` - the matrix containing v1 argument: the low bound of the averaged range of values for every element of the result.
`maxValues` - the matrix containing v2 argument: the high bound of the averaged range of values for every element of the result.
`pattern` - the pattern: the shape of the aperture.
`filler` - the reserved value, returned when r(v1*σ)≥r(v2*σ), or one of the special keys `FILL_MIN_VALUE`, `FILL_MAX_VALUE`, `FILL_NEAREST_VALUE`, which mean using of special calculation modes B, C, D.
Returns:
the mean between 2 given values of the source matrix.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`asMeanBetweenValues(Matrix, Matrix, Matrix, Pattern, double)`, `meanBetweenValues(Matrix, Matrix, Matrix, Matrix, Pattern, double)`
• #### meanBetweenValues

```void meanBetweenValues(Matrix<? extends UpdatablePArray> dest,
Matrix<? extends PArray> src,
Matrix<? extends PArray> minValues,
Matrix<? extends PArray> maxValues,
Pattern pattern,
double filler)```
Equivalent to `meanBetweenValues(Matrix, Matrix, Matrix, Pattern, double)` method, but the result matrix will be placed in the dest argument.

If the element type of dest matrix is fixed-point — boolean, char, byte, short, int or long — then we need to round the real mean, defined in the comments to this class. In this case, the found mean value m is usually truncated to its integer part m⌋=(long)m (remember that the mean value, according to our definition, is always ≥0). More precisely, the rules of casting the floating-point means to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

Parameters:
`dest` - the target matrix.
`src` - the source matrix.
`minValues` - the matrix containing v1 argument: the low bound of the averaged range of values for every element of the result.
`maxValues` - the matrix containing v2 argument: the high bound of the averaged range of values for every element of the result.
`pattern` - the pattern: the shape of the aperture.
`filler` - the reserved value, returned when r(v1*σ)≥r(v2*σ), or one of the special keys `FILL_MIN_VALUE`, `FILL_MAX_VALUE`, `FILL_NEAREST_VALUE`, which mean using of special calculation modes B, C, D.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`asMeanBetweenValues(Matrix, Matrix, Matrix, Pattern, double)`, `meanBetweenValues(Matrix, Matrix, Matrix, Pattern, double)`
• #### asMean

```Matrix<? extends PArray> asMean(Matrix<? extends PArray> src,
Pattern pattern)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the mean of the source matrix by the specified pattern.

More precisely, this method is equivalent to `asFunctionOfSum`(src, pattern, meanFunc), where the function meanFunc is:

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real mean, defined above. In this case, the found mean value m is usually truncated to its integer part m⌋=(long)m (remember that the mean value, according to our definition, is always ≥0). More precisely, the rules of casting the floating-point means to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

The described rounding rule explains, why we add 0.5 to the mean in the case of a fixed-point source elements. Namely, in this case the combination of adding 0.5 and further truncation to the integer part works as rounding to the nearest integer: m+0.5⌋=Math.round(m) (excepting some rare cases when the real mean m is a strictly half-integer: m=2k, kZ). In other words, this behaviour provides the maximal possible precision of the returned integer mean.

Note: the behaviour of this method is similar to `asMeanBetweenPercentiles`(src, 0, N, pattern, anyFiller), where N = pattern.`pointCount()`, if the histogram is processed in the simple histogram model (see `comments to SummingHistogram class`). Really, in this case the mean between 2 percentiles is equal to

(S(r2)−S(r1)) / ((r2r1)*σ) = S(N) / (N*σ) = (Σ 0≤j<M(j+0.5)*b[j]) / (N*σ)

In the simplest case, when the source elements are real numbers in the "standard" allowed range 0.0..1.0, we have σ = M (the histogram length), ai = ⌊vi*M, and this expression is equal to

(Σ 0≤i<N(ai+0.5)) / (NM) = (v'0+v'1+...+v'N−1) / N + 0.5 / M ≈ (v0+v1+...+vN−1) / N

where v'i = ai/M is an attempt to represent the real number vi with the given precision μ=log2M bits and a correction 0.5/M is very little for large M.

In another simplest case, when the source elements are integer numbers, σ=1 and the elements vi are non-negative integers, we have ai = vi, and this expression is equal to

(Σ 0≤i<N(vi+0.5)) / N = (v0+v1+...+vN−1) / N + 0.5
Parameters:
`src` - the source matrix.
`pattern` - the pattern: the shape of the aperture.
Returns:
the "lazy" matrix containing the mean of the source matrix.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`mean(Matrix, Pattern)`, `mean(Matrix, Matrix, Pattern)`
• #### mean

```Matrix<? extends UpdatablePArray> mean(Matrix<? extends PArray> src,
Pattern pattern)```
Returns a new updatable matrix, containing the mean of the source matrix by the specified pattern.

More precisely, this method is equivalent to `functionOfSum`(src, pattern, meanFunc), where the function meanFunc is:

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real mean, defined above. In this case, the found mean value m is usually truncated to its integer part m⌋=(long)m (remember that the mean value, according to our definition, is always ≥0). More precisely, the rules of casting the floating-point means to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

The described rounding rule explains, why we add 0.5 to the mean in the case of a fixed-point source elements. Namely, in this case the combination of adding 0.5 and further truncation to the integer part works as rounding to the nearest integer: m+0.5⌋=Math.round(m) (excepting some rare cases when the real mean m is a strictly half-integer: m=2k, kZ). In other words, this behaviour provides the maximal possible precision of the returned integer mean.

Note: the behaviour of this method is similar to `meanBetweenPercentiles`(src, 0, N, pattern, anyFiller), where N = pattern.`pointCount()`, if the histogram is processed in the simple histogram model (see `comments to SummingHistogram class`). Really, in this case the mean between 2 percentiles is equal to

(S(r2)−S(r1)) / ((r2r1)*σ) = S(N) / (N*σ) = (Σ 0≤j<M(j+0.5)*b[j]) / (N*σ)

In the simplest case, when the source elements are real numbers in the "standard" allowed range 0.0..1.0, we have σ = M (the histogram length), ai = ⌊vi*M, and this expression is equal to

(Σ 0≤i<N(ai+0.5)) / (NM) = (v'0+v'1+...+v'N−1) / N + 0.5 / M ≈ (v0+v1+...+vN−1) / N

where v'i = ai/M is an attempt to represent the real number vi with the given precision μ=log2M bits and a correction 0.5/M is very little for large M.

In another simplest case, when the source elements are integer numbers, σ=1 and the elements vi are non-negative integers, we have ai = vi, and this expression is equal to

(Σ 0≤i<N(vi+0.5)) / N = (v0+v1+...+vN−1) / N + 0.5
Parameters:
`src` - the source matrix.
`pattern` - the pattern: the shape of the aperture.
Returns:
the mean of the source matrix.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`asMean(Matrix, Pattern)`, `mean(Matrix, Matrix, Pattern)`
• #### mean

```void mean(Matrix<? extends UpdatablePArray> dest,
Matrix<? extends PArray> src,
Pattern pattern)```
Equivalent to `mean(Matrix, Pattern)` method, but the result matrix will be placed in the dest argument.

If the element type of dest matrix is fixed-point — boolean, char, byte, short, int or long — then we need to round the real mean, defined above. In this case, the found mean value m is usually truncated to its integer part m⌋=(long)m (remember that the mean value, according to our definition, is always ≥0). More precisely, the rules of casting the floating-point means to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

The described rounding rule explains, why we add 0.5 to the mean in the case of a fixed-point source elements. Namely, in this case the combination of adding 0.5 and further truncation to the integer part works as rounding to the nearest integer: m+0.5⌋=Math.round(m) (excepting some rare cases when the real mean m is a strictly half-integer: m=2k, kZ). In other words, this behaviour provides the maximal possible precision of the returned integer mean.

Note: the behaviour of this method is similar to `meanBetweenPercentiles`(src, 0, N, pattern, anyFiller), where N = pattern.`pointCount()`, if the histogram is processed in the simple histogram model (see `comments to SummingHistogram class`). Really, in this case the mean between 2 percentiles is equal to

(S(r2)−S(r1)) / ((r2r1)*σ) = S(N) / (N*σ) = (Σ 0≤j<M(j+0.5)*b[j]) / (N*σ)

In the simplest case, when the source elements are real numbers in the "standard" allowed range 0.0..1.0, we have σ = M (the histogram length), ai = ⌊vi*M, and this expression is equal to

(Σ 0≤i<N(ai+0.5)) / (NM) = (v'0+v'1+...+v'N−1) / N + 0.5 / M ≈ (v0+v1+...+vN−1) / N

where v'i = ai/M is an attempt to represent the real number vi with the given precision μ=log2M bits and a correction 0.5/M is very little for large M.

In another simplest case, when the source elements are integer numbers, σ=1 and the elements vi are non-negative integers, we have ai = vi, and this expression is equal to

(Σ 0≤i<N(vi+0.5)) / N = (v0+v1+...+vN−1) / N + 0.5
Parameters:
`dest` - the target matrix.
`src` - the source matrix.
`pattern` - the pattern: the shape of the aperture.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`asMean(Matrix, Pattern)`, `mean(Matrix, Pattern)`
• #### asFunctionOfSum

```Matrix<? extends PArray> asFunctionOfSum(Matrix<? extends PArray> src,
Pattern pattern,
Func processingFunc)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the result of some given function f(S) of the aperture sum S of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "aperture sum" term. The `element type` of the created matrix is the same as the element type of the source one.

The function, applied to each calculated aperture sum S, is specified via processingFunc argument. Namely, for each aperture position this method calculates the aperture sum S of the source matrix and returns processingFunc.`get`(S) in the corresponding element of the resulting matrix.

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real function result. In this case, the found function result f is usually truncated to its integer part (long)f. More precisely, the rules of casting the floating-point function results to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

This method can be considered as a generalization of `asMean(Matrix, Pattern)`.

Parameters:
`src` - the source matrix.
`pattern` - the pattern: the shape of the aperture.
`processingFunc` - the function, which should be applied to every calculated aperture sum.
Returns:
the "lazy" matrix containing the result of the given function for the aperture sum of the source matrix.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`functionOfSum(Matrix, Pattern, Func)`, `functionOfSum(Matrix, Matrix, Pattern, Func)`
• #### functionOfSum

```Matrix<? extends UpdatablePArray> functionOfSum(Matrix<? extends PArray> src,
Pattern pattern,
Func processingFunc)```
Returns a new updatable matrix, containing the result of some given function f(S) of the aperture sum S of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "aperture sum" term. The `element type` of the created matrix is the same as the element type of the source one.

The function, applied to each calculated aperture sum S, is specified via processingFunc argument. Namely, for each aperture position this method calculates the aperture sum S of the source matrix and returns processingFunc.`get`(S) in the corresponding element of the resulting matrix.

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real function result. In this case, the found function result f is usually truncated to its integer part (long)f. More precisely, the rules of casting the floating-point function results to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

This method can be considered as a generalization of `mean(Matrix, Pattern)`.

Parameters:
`src` - the source matrix.
`pattern` - the pattern: the shape of the aperture.
`processingFunc` - the function, which should be applied to every calculated aperture sum.
Returns:
the result of the given function for the aperture sum of the source matrix.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`asFunctionOfSum(Matrix, Pattern, Func)`, `functionOfSum(Matrix, Matrix, Pattern, Func)`
• #### functionOfSum

```void functionOfSum(Matrix<? extends UpdatablePArray> dest,
Matrix<? extends PArray> src,
Pattern pattern,
Func processingFunc)```
Equivalent to `functionOfSum(Matrix, Pattern, Func)` method, but the result matrix will be placed in the dest argument.

If the element type of dest matrix is fixed-point — boolean, char, byte, short, int or long — then we need to round the real function result. In this case, the found function result f is usually truncated to its integer part (long)f. More precisely, the rules of casting the floating-point function results to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

This method can be considered as a generalization of `mean(Matrix, Matrix, Pattern)`.

Parameters:
`dest` - the target matrix.
`src` - the source matrix.
`pattern` - the pattern: the shape of the aperture.
`processingFunc` - the function, which should be applied to every calculated aperture sum.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`asFunctionOfSum(Matrix, Pattern, Func)`, `functionOfSum(Matrix, Pattern, Func)`
• #### asFunctionOfPercentilePair

```Matrix<? extends PArray> asFunctionOfPercentilePair(Matrix<? extends PArray> src,
Matrix<? extends PArray> percentileIndexes1,
Matrix<? extends PArray> percentileIndexes2,
Pattern pattern,
Func processingFunc)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the result of some given function f(v, v1,v2) of the source matrix v and two percentiles v1,v2 of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "percentile" term. The real indexes r of two percentiles for every element of the result are equal to the corresponding elements of percentileIndexes1 (for v1) or percentileIndexes2 matrix (for v2). The `element type` of the created matrix is the same as the element type of the source one.

The function, applied to each calculated three (v,v1,v2), is specified via processingFunc argument. Namely, for each aperture position x this method takes the value v — the element of the source matrix src at this aperture position x, calculates two percentiles v1 and v2 of the source matrix and returns processingFunc.`get`(v,v1,v2) in the corresponding element of the resulting matrix.

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real function result. In this case, the found function result f is usually truncated to its integer part (long)f. More precisely, the rules of casting the floating-point function results to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

You can get the same results by 2 calls of `asPercentile(Matrix, Matrix, Pattern)` method for both matrices of percentile indexes and applying the function to them and to the source matrix via `Matrices.asFuncMatrix(Func, Class, Matrix, Matrix, Matrix)` method. But such a way works slower and is less convenient, than this method. A typical application of this method in image processing area is the contrasting image — in this case, we recommend using `ContrastingFunc` object as processingFunc argument.

Parameters:
`src` - the source matrix.
`percentileIndexes1` - the 1st matrix containing r argument: the indexes of the 1st percentile v1 for every element of the result.
`percentileIndexes2` - the 2nd matrix containing r argument: the indexes of the 2nd percentile v2 for every element of the result.
`pattern` - the pattern: the shape of the aperture.
`processingFunc` - the function, which should be applied to every calculated three (v,v1,v2), where v is the element of the source matrix, v1 and v2 are the corresponding percentiles.
Returns:
the "lazy" matrix containing the result of the given function.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`asFunctionOfPercentilePair(Matrix, double, double, Pattern, Func)`, `functionOfPercentilePair(Matrix, Matrix, Matrix, Pattern, Func)`, `functionOfPercentilePair(Matrix, Matrix, Matrix, Matrix, Pattern, Func)`
• #### asFunctionOfPercentilePair

```Matrix<? extends PArray> asFunctionOfPercentilePair(Matrix<? extends PArray> src,
double percentileIndex1,
double percentileIndex2,
Pattern pattern,
Func processingFunc)```
Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the result of some given function f(v, v1,v2) of the source matrix v and two percentiles v1,v2 of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "percentile" term. The real indexes r of two percentiles for every element of the result are equal to percentileIndex1 (for v1) or percentileIndex2 argument (for v2). The `element type` of the created matrix is the same as the element type of the source one.

This method is equivalent to

````asFunctionOfPercentilePair`(src,
src.matrix(`Arrays.nDoubleCopies`(src.size(), percentileIndex1),
src.matrix(`Arrays.nDoubleCopies`(src.size(), percentileIndex1),
pattern, processingFunc)```

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real function result. In this case, the found function result f is usually truncated to its integer part (long)f. More precisely, the rules of casting the floating-point function results to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

You can get the same results by 2 calls of `asPercentile(Matrix, double, Pattern)` method for both matrices of percentile indexes and applying the function to them and to the source matrix via `Matrices.asFuncMatrix(Func, Class, Matrix, Matrix, Matrix)` method. But such a way works slower and is less convenient, than this method. A typical application of this method in image processing area is the contrasting image — in this case, we recommend using `ContrastingFunc` object as processingFunc argument.

Parameters:
`src` - the source matrix.
`percentileIndex1` - the 1st r argument: the index of the 1st percentile v1.
`percentileIndex2` - the 2nd r argument: the index of the 2nd percentile v2.
`pattern` - the pattern: the shape of the aperture.
`processingFunc` - the function, which should be applied to every calculated three (v,v1,v2), where v is the element of the source matrix, v1 and v2 are the corresponding percentiles.
Returns:
the "lazy" matrix containing the result of the given function.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`asFunctionOfPercentilePair(Matrix, Matrix, Matrix, Pattern, Func)`, `functionOfPercentilePair(Matrix, double, double, Pattern, Func)`, `functionOfPercentilePair(Matrix, Matrix, double, double, Pattern, Func)`
• #### functionOfPercentilePair

```Matrix<? extends UpdatablePArray> functionOfPercentilePair(Matrix<? extends PArray> src,
Matrix<? extends PArray> percentileIndexes1,
Matrix<? extends PArray> percentileIndexes2,
Pattern pattern,
Func processingFunc)```
Returns a new updatable matrix, containing the result of some given function f(v, v1,v2) of the source matrix v and two percentiles v1,v2 of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "percentile" term. The real indexes r of two percentiles for every element of the result are equal to the corresponding elements of percentileIndexes1 (for v1) or percentileIndexes2 matrix (for v2). The `element type` of the created matrix is the same as the element type of the source one.

The function, applied to each calculated three (v,v1,v2), is specified via processingFunc argument. Namely, for each aperture position x this method takes the value v — the element of the source matrix src at this aperture position x, calculates two percentiles v1 and v2 of the source matrix and returns processingFunc.`get`(v,v1,v2) in the corresponding element of the resulting matrix.

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real function result. In this case, the found function result f is usually truncated to its integer part (long)f. More precisely, the rules of casting the floating-point function results to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

You can get the same results by 2 calls of `percentile(Matrix, Matrix, Pattern)` method for both matrices of percentile indexes and applying the function to them and to the source matrix via `Matrices.asFuncMatrix(Func, Class, Matrix, Matrix, Matrix)` method. But such a way works slower and is less convenient, than this method. A typical application of this method in image processing area is the contrasting image — in this case, we recommend using `ContrastingFunc` object as processingFunc argument.

Parameters:
`src` - the source matrix.
`percentileIndexes1` - the 1st matrix containing r argument: the indexes of the 1st percentile v1 for every element of the result.
`percentileIndexes2` - the 2nd matrix containing r argument: the indexes of the 2nd percentile v2 for every element of the result.
`pattern` - the pattern: the shape of the aperture.
`processingFunc` - the function, which should be applied to every calculated three (v,v1,v2), where v is the element of the source matrix, v1 and v2 are the corresponding percentiles.
Returns:
the result of the given function.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`functionOfPercentilePair(Matrix, double, double, Pattern, Func)`, `asFunctionOfPercentilePair(Matrix, Matrix, Matrix, Pattern, Func)`, `functionOfPercentilePair(Matrix, Matrix, Matrix, Matrix, Pattern, Func)`
• #### functionOfPercentilePair

```Matrix<? extends UpdatablePArray> functionOfPercentilePair(Matrix<? extends PArray> src,
double percentileIndex1,
double percentileIndex2,
Pattern pattern,
Func processingFunc)```
Returns a new updatable matrix, containing the result of some given function f(v, v1,v2) of the source matrix v and two percentiles v1,v2 of the source matrix by the specified pattern. See the `comments to this class`, section 4 about the "percentile" term. The real indexes r of two percentiles for every element of the result are equal to percentileIndex1 (for v1) or percentileIndex2 argument (for v2). The `element type` of the created matrix is the same as the element type of the source one.

This method is equivalent to

````functionOfPercentilePair`(src,
src.matrix(`Arrays.nDoubleCopies`(src.size(), percentileIndex1),
src.matrix(`Arrays.nDoubleCopies`(src.size(), percentileIndex1),
pattern, processingFunc)```

If the element type of the source matrix (and, thus, of the result) is fixed-point — boolean, char, byte, short, int or long — then we need to round the real function result. In this case, the found function result f is usually truncated to its integer part (long)f. More precisely, the rules of casting the floating-point function results to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

You can get the same results by 2 calls of `percentile(Matrix, double, Pattern)` method for both matrices of percentile indexes and applying the function to them and to the source matrix via `Matrices.asFuncMatrix(Func, Class, Matrix, Matrix, Matrix)` method. But such a way works slower and is less convenient, than this method. A typical application of this method in image processing area is the contrasting image — in this case, we recommend using `ContrastingFunc` object as processingFunc argument.

Parameters:
`src` - the source matrix.
`percentileIndex1` - the 1st r argument: the index of the 1st percentile v1.
`percentileIndex2` - the 2nd r argument: the index of the 2nd percentile v2.
`pattern` - the pattern: the shape of the aperture.
`processingFunc` - the function, which should be applied to every calculated three (v,v1,v2), where v is the element of the source matrix, v1 and v2 are the corresponding percentiles.
Returns:
the result of the given function.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`functionOfPercentilePair(Matrix, Matrix, Matrix, Pattern, Func)`, `asFunctionOfPercentilePair(Matrix, double, double, Pattern, Func)`, `functionOfPercentilePair(Matrix, Matrix, double, double, Pattern, Func)`
• #### functionOfPercentilePair

```void functionOfPercentilePair(Matrix<? extends UpdatablePArray> dest,
Matrix<? extends PArray> src,
Matrix<? extends PArray> percentileIndexes1,
Matrix<? extends PArray> percentileIndexes2,
Pattern pattern,
Func processingFunc)```
Equivalent to `functionOfPercentilePair(Matrix, Matrix, Matrix, Pattern, Func)` method, but the result matrix will be placed in the dest argument.

If the element type of dest matrix is fixed-point — boolean, char, byte, short, int or long — then we need to round the real function result. In this case, the found function result f is usually truncated to its integer part (long)f. More precisely, the rules of casting the floating-point function results to the desired element type are the same as in `Arrays.asFuncArray(boolean, Func, Class, PArray...)` method with the argument truncateOverflows=true.

Parameters:
`dest` - the target matrix.
`src` - the source matrix.
`percentileIndexes1` - the 1st matrix containing r argument: the indexes of the 1st percentile v1 for every element of the result.
`percentileIndexes2` - the 2nd matrix containing r argument: the indexes of the 2nd percentile v2 for every element of the result.
`pattern` - the pattern: the shape of the aperture.
`processingFunc` - the function, which should be applied to every calculated three (v,v1,v2), where v is the element of the source matrix, v1 and v2 are the corresponding percentiles.
Throws:
`java.lang.NullPointerException` - if one of the arguments is null.
`SizeMismatchException` - if the passed matrices have different dimensions.
`java.lang.IllegalArgumentException` - if the number of the pattern dimensions pattern.`dimCount()` is not equal to src.`dimCount()`.
See Also:
`functionOfPercentilePair(Matrix, Matrix, double, double, Pattern, Func)`, `asFunctionOfPercentilePair(Matrix, Matrix, Matrix, Pattern, Func)`, `functionOfPercentilePair(Matrix, Matrix, Matrix, Pattern, Func)`