Package 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 x−pi = (x0−pi0, x1−pi1, ..., xn−1−pi,n−1) for all pi∈P (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 x−pi.
     
  2. For every point x' = x−pi 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≤xk−pi,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 = xk−pi,k. In particular, it is true for all implementations offered by this package. If the point x' = x−pi lies outside the matrix (x'k<0 or x'k≥M.dim(k) for some k), then:
  3. So, for every point x we have an aperture, consisting of N=P.pointCount() "neighbour" points x−pi, 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:
    • ai = min(M−1, ⌊max(0, vi) * σ⌋) (here and below ⌊y⌋ means the integer part of y or (long)y for non-negative numbers, M and σ are defined below); in other words, ai is an integer part of σvi, truncated to 0..M−1 range of allowed histogram indexes;
    • the histogram length M is the global parameter of this object and is equal to some power of two: M=2μ, μ=0,1,2... There is a guarantee that if the matrix is fixed-point (M.Matrix.elementType() is boolean, char, byte, short, int or long), then μ≤β, where β is the number of bits per element: β = M.array().bitsPerElement(). If this object is an instance of BasicRankMorphology, then μ = bitLevels[bitLevels.length-1] for floating-point matrix elements (M.Matrix.elementType() is float or double) or μ = min(bitLevels[bitLevels.length-1], β) for fixed-point matrix elements, where bitLevels is an array of bit levels, specified while instantiating this class via the last argument of BasicRankMorphology.getInstance(ArrayContext, double, CustomRankPrecision) method;
    • the real number σ ("scale") is equal to M for a floating-point matrix or equal to M/2β=2μ−β, β = M.array().bitsPerElement() for a fixed-point matrix. So, in the case of a fixed-point matrix there is a guarantee that 1/σ is a positive integer number (2β−μ).
    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[0], b[1], ..., 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)) / ((r2−r1)*σ) if r1<r2 or some reserved value filler if r1≥r2, 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 v1≥v2, 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 v1≥v2, 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 classes, implementing this interface, are immutable and thread-safe: there are no ways to modify settings of the created instance.

Author:
Daniel Alievsky

  • Field Details

  • Method Details

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

      • either the integer result of Histogram.iValue (b, (long)Math.floor(r)), if this object works in the simple histogram model (where b is the histogram, corresponding to every aperture position),
      • or the integer result of Histogram.iPreciseValue (b, r), if it works in the precise histogram model.
      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:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

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

      • either the integer result of Histogram.iValue (b, (long)Math.floor(r)), if this object works in the simple histogram model (where b is the histogram, corresponding to every aperture position),
      • or the integer result of Histogram.iPreciseValue (b, r), if it works in the precise histogram model.
      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:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

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

      • either the integer result of Histogram.iValue (b, (long)Math.floor(r)), if this object works in the simple histogram model (where b is the histogram, corresponding to every aperture position),
      • or the integer result of Histogram.iPreciseValue (b, r), if it works in the precise histogram model.
      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:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

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

      • either the integer result of Histogram.iValue (b, (long)Math.floor(r)), if this object works in the simple histogram model (where b is the histogram, corresponding to every aperture position),
      • or the integer result of Histogram.iPreciseValue (b, r), if it works in the precise histogram model.
      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:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • percentile

      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.

      If the element type of the passed dest matrix is the same as the element type of the source one, the result, saved in dest, will be identically equal to the result of percentile(Matrix, Matrix, Pattern) method with the same src, percentileIndexes and pattern arguments. In other case, the result, saved in dest, will be equal to 

      Matrices.asFuncMatrix(true, Func.IDENTITY,
     dest.array().type(), percentile(src, percentileIndexes, pattern))

      So, even if the precision of dest matrix is better than the precision of src — for example, if src.elementType() is byte, but dest.elementType() is double — this method does not try to calculate more precise percentile and rounds results like asPercentile(Matrix, Matrix, Pattern) and percentile(Matrix, Matrix, Pattern) methods.

      Parameters:
      dest - the target matrix.
      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.
      Throws:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • percentile

      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.

      This method is equivalent to 

      percentile(dest, src, src.matrix(Arrays.nDoubleCopies(src.size(), percentileIndex), pattern)
      Parameters:
      dest - the target matrix.
      src - the source matrix.
      percentileIndex - r argument of the percentile.
      pattern - the pattern: the shape of the aperture.
      Throws:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • asRank

      <T extends PArray> Matrix<T> asRank(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:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      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

      <T extends PArray> Matrix<? extends T> rank(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. 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 updatable, and the class of its built-in array implements one of the basic interfaces UpdatableBitArray, UpdatableCharArray, UpdatableByteArray, UpdatableShortArray, UpdatableIntArray, UpdatableLongArray, UpdatableFloatArray or UpdatableDoubleArray. 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. Instead of these classes, you can also pass one of corresponding immutable interfaces BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray, FloatArray or DoubleArray: the result will be the same. 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. The less result precision allows you to save memory.

      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 rank of the given values.
      Throws:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to baseMatrix.dimCount(), or if requiredType is not one of classes UpdatableBitArray.class / BitArray.class, UpdatableCharArray.class / CharArray.class, UpdatableByteArray.class / ByteArray.class, UpdatableShortArray.class / ShortArray.class, UpdatableIntArray.class / IntArray.class, UpdatableLongArray.class / LongArray.class, UpdatableFloatArray.class / FloatArray.class or UpdatableDoubleArray.class / DoubleArray.class.
      See Also:

    • 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:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to baseMatrix.dimCount().
      See Also:

    • 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 r1≥r2.
      Returns:
      the "lazy" matrix containing the mean between 2 given percentiles of the source matrix.
      Throws:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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 r1≥r2.
      Returns:
      the "lazy" matrix containing the mean between 2 given percentiles of the source matrix.
      Throws:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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 r1≥r2.
      Returns:
      the mean between 2 given percentiles of the source matrix.
      Throws:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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 r1≥r2.
      Returns:
      the mean between 2 given percentiles of the source matrix.
      Throws:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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 r1≥r2.
      Throws:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • meanBetweenPercentiles

      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.

      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.
      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 r1≥r2.
      Throws:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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:
      • if filler argument is FILL_MIN_VALUE (Double.NEGATIVE_INFINITY), the mode B is used;
      • if filler argument is FILL_MAX_VALUE (Double.POSITIVE_INFINITY), the mode C is used;
      • if filler argument is FILL_NEAREST_VALUE (Double.NaN), the mode D is used;
      • if filler argument contains any other value, the mode A is used and this argument specifies the reserved value filler.
      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:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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:
      • if filler argument is FILL_MIN_VALUE (Double.NEGATIVE_INFINITY), the mode B is used;
      • if filler argument is FILL_MAX_VALUE (Double.POSITIVE_INFINITY), the mode C is used;
      • if filler argument is FILL_NEAREST_VALUE (Double.NaN), the mode D is used;
      • if filler argument contains any other value, the mode A is used and this argument specifies the reserved value filler.
      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:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

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

      • LinearFunc.getInstance(0.0, 1.0/N), N = pattern.pointCount(), if the source matrix is floating-point (src.elementType() is float or double) — in other words, this method calculates the usual mean of all elements in the aperture: (v0+v1+...+vN−1) / N;
      • LinearFunc.getInstance(0.5, 1.0/N), N = pattern.pointCount(), if the source matrix is fixed-point (src.elementType() is boolean, char, byte, short, int or long) — in other words, this method calculates the mean of all elements in the aperture plus 0.5: (v0+v1+...+vN−1) / N + 0.5.

      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+½, k∈Z). 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)) / ((r2−r1)*σ) = 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:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

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

      • LinearFunc.getInstance(0.0, 1.0/N), N = pattern.pointCount(), if the source matrix is floating-point (src.elementType() is float or double) — in other words, this method calculates the usual mean of all elements in the aperture: (v0+v1+...+vN−1) / N;
      • LinearFunc.getInstance(0.5, 1.0/N), N = pattern.pointCount(), if the source matrix is fixed-point (src.elementType() is boolean, char, byte, short, int or long) — in other words, this method calculates the mean of all elements in the aperture plus 0.5: (v0+v1+...+vN−1) / N + 0.5.

      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+½, k∈Z). 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)) / ((r2−r1)*σ) = 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:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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+½, k∈Z). 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)) / ((r2−r1)*σ) = 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:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • 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:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also:

    • functionOfPercentilePair

      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.

      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.
      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.
      Throws:
      NullPointerException - if one of the arguments is null.
      SizeMismatchException - if the passed matrices have different dimensions.
      IllegalArgumentException - if the number of the pattern dimensions pattern.dimCount() is not equal to src.dimCount().
      See Also: