Package net.algart.matrices.morphology

Class TiledRankMorphology

java.lang.Object
net.algart.matrices.morphology.TiledMorphology
net.algart.matrices.morphology.TiledRankMorphology
All Implemented Interfaces:
ArrayProcessor, ArrayProcessorWithContextSwitching, Morphology, RankMorphology
public class TiledRankMorphology extends TiledMorphology implements RankMorphology

The filter allowing to transform any RankMorphology object to another instance of that interface, which uses some given tiler for processing the source matrices (arguments of RankMorphology methods).

This object is built on the base of some parent object, implementing RankMorphology, and some tiler (an instance of TiledApertureProcessorFactory class). This object works almost identically to the parent object with the only difference, that it uses the specified tiler for performing all operations.

More precisely, each method of this object creates an implementation p of ApertureProcessor interface. The only thing, performed by process method of that object p, is calling the same method of parent object with the arguments of p.process(dest,src) method (the source matrix or matrices are retrieved from src, the result is saved into dest). The dependence aperture p.dependenceAperture(...) is calculated automatically on the base of the patterns and the performed operation. Then, the method of this object executes the required operation with help of tiler().tile(p).process(dest,src) call — the source matrix or matrices are passed via src, the result is retrieved from dest. As a result, the same operation is performed tile-by-tile.

The methods "asOperation", returning a view of the passed sources matrices (like TiledMorphology.asDilation(Matrix, Pattern), asPercentile(Matrix, double, Pattern), asRank(Class, Matrix, Matrix, Pattern), etc.) are an exception from this rule. These methods of this class works in the same way, as in ContinuedRankMorphology class, the continuation mode of which is equal to tiler().continuationMode().

Note: in improbable cases, when the dimensions of the source matrix and/or the sizes of the pattern are extremely large (about 263), so that the necessary appended matrices should have dimensions or total number of elements, greater than Long.MAX_VALUE, the methods of this class throw IndexOutOfBoundsException and do nothing. See comments to TiledApertureProcessorFactory class, "Restriction" section for precise details. Of course, these are very improbable cases.

This class is immutable and thread-safe: there are no ways to modify settings of the created instance.

Author:
Daniel Alievsky

  • Method Details

    • getInstance

      public static TiledRankMorphology getInstance(RankMorphology parent, TiledApertureProcessorFactory tiler)
      Returns new instance of this class with the passed parent RankMorphology object and the specified processing tiler.

      Note: the context of the created object is retrieved from parent.context(), and the context of the passed tiler is automatically replaced with the same one — the current tiler of the created object is tiler.context(newInstance.context()). It means that the context of the passed tiler is not important and can be null.

      Parameters:
      parent - parent object: the instance of Morphology interface that will perform all operations.
      tiler - the tiler, which will be used for processing matrices by this class.
      Returns:
      new instance of this class.
      Throws:
      NullPointerException - if parent or tiler argument is null.

    • parent

      public RankMorphology parent()
      Returns the parent RankMorphology object, passed to getInstance(RankMorphology, TiledApertureProcessorFactory) method.
      Overrides:
      parent in class TiledMorphology
      Returns:
      the parent RankMorphology object.

    • context

      public RankMorphology context(ArrayContext newContext)
      Switches the context: returns an instance, identical to this one excepting that it uses the specified newContext for all operations. Usually, the returned instance is used only for performing a subtask of the full task.

      More precisely, this method is equivalent to getInstance(parent().context(newContext), tiler()).

      Specified by:
      context in interface ArrayProcessorWithContextSwitching
      Specified by:
      context in interface Morphology
      Specified by:
      context in interface RankMorphology
      Overrides:
      context in class TiledMorphology
      Parameters:
      newContext - another context, used by the returned instance; may be null.
      Returns:
      new instance with another context.

    • asPercentile

      public Matrix<? extends PArray> asPercentile(Matrix<? extends PArray> src, Matrix<? extends PArray> percentileIndexes, Pattern pattern)
      Description copied from interface: RankMorphology
      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], β).
      Specified by:
      asPercentile in interface RankMorphology
      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.
      See Also:

    • asPercentile

      public Matrix<? extends PArray> asPercentile(Matrix<? extends PArray> src, double percentileIndex, Pattern pattern)
      Description copied from interface: RankMorphology
      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], β).
      Specified by:
      asPercentile in interface RankMorphology
      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.
      See Also:

    • asRank

      public <T extends PArray> Matrix<T> asRank(Class<? extends T> requiredType, Matrix<? extends PArray> baseMatrix, Matrix<? extends PArray> rankedMatrix, Pattern pattern)
      Description copied from interface: RankMorphology
      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.

      Specified by:
      asRank in interface RankMorphology
      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.
      See Also:

    • asMeanBetweenPercentiles

      public Matrix<? extends PArray> asMeanBetweenPercentiles(Matrix<? extends PArray> src, Matrix<? extends PArray> fromPercentileIndexes, Matrix<? extends PArray> toPercentileIndexes, Pattern pattern, double filler)
      Description copied from interface: RankMorphology
      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.

      Specified by:
      asMeanBetweenPercentiles in interface RankMorphology
      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.
      See Also:

    • asMeanBetweenPercentiles

      public Matrix<? extends PArray> asMeanBetweenPercentiles(Matrix<? extends PArray> src, double fromPercentileIndex, double toPercentileIndex, Pattern pattern, double filler)
      Description copied from interface: RankMorphology
      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.

      Specified by:
      asMeanBetweenPercentiles in interface RankMorphology
      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.
      See Also:

    • asMeanBetweenValues

      public Matrix<? extends PArray> asMeanBetweenValues(Matrix<? extends PArray> src, Matrix<? extends PArray> minValues, Matrix<? extends PArray> maxValues, Pattern pattern, double filler)
      Description copied from interface: RankMorphology
      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.

      Specified by:
      asMeanBetweenValues in interface RankMorphology
      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 RankMorphology.FILL_MIN_VALUE, RankMorphology.FILL_MAX_VALUE, RankMorphology.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.
      See Also:

    • asMean

      public Matrix<? extends PArray> asMean(Matrix<? extends PArray> src, Pattern pattern)
      Description copied from interface: RankMorphology
      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
      Specified by:
      asMean in interface RankMorphology
      Parameters:
      src - the source matrix.
      pattern - the pattern: the shape of the aperture.
      Returns:
      the "lazy" matrix containing the mean of the source matrix.
      See Also:

    • asFunctionOfSum

      public Matrix<? extends PArray> asFunctionOfSum(Matrix<? extends PArray> src, Pattern pattern, Func processingFunc)
      Description copied from interface: RankMorphology
      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 RankMorphology.asMean(Matrix, Pattern).

      Specified by:
      asFunctionOfSum in interface RankMorphology
      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.
      See Also:

    • asFunctionOfPercentilePair

      public Matrix<? extends PArray> asFunctionOfPercentilePair(Matrix<? extends PArray> src, Matrix<? extends PArray> percentileIndexes1, Matrix<? extends PArray> percentileIndexes2, Pattern pattern, Func processingFunc)
      Description copied from interface: RankMorphology
      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 RankMorphology.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.

      Specified by:
      asFunctionOfPercentilePair in interface RankMorphology
      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.
      See Also:

    • asFunctionOfPercentilePair

      public Matrix<? extends PArray> asFunctionOfPercentilePair(Matrix<? extends PArray> src, double percentileIndex1, double percentileIndex2, Pattern pattern, Func processingFunc)
      Description copied from interface: RankMorphology
      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 RankMorphology.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.

      Specified by:
      asFunctionOfPercentilePair in interface RankMorphology
      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.
      See Also:

    • percentile

      public Matrix<? extends UpdatablePArray> percentile(Matrix<? extends PArray> src, Matrix<? extends PArray> percentileIndexes, Pattern pattern)
      Description copied from interface: RankMorphology
      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], β).
      Specified by:
      percentile in interface RankMorphology
      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.
      See Also:

    • percentile

      public Matrix<? extends UpdatablePArray> percentile(Matrix<? extends PArray> src, double percentileIndex, Pattern pattern)
      Description copied from interface: RankMorphology
      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], β).
      Specified by:
      percentile in interface RankMorphology
      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.
      See Also:

    • rank

      public <T extends PArray> Matrix<? extends T> rank(Class<? extends T> requiredType, Matrix<? extends PArray> baseMatrix, Matrix<? extends PArray> rankedMatrix, Pattern pattern)
      Description copied from interface: RankMorphology
      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.

      Specified by:
      rank in interface RankMorphology
      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.
      See Also:

    • meanBetweenPercentiles

      public Matrix<? extends UpdatablePArray> meanBetweenPercentiles(Matrix<? extends PArray> src, Matrix<? extends PArray> fromPercentileIndexes, Matrix<? extends PArray> toPercentileIndexes, Pattern pattern, double filler)
      Description copied from interface: RankMorphology
      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.

      Specified by:
      meanBetweenPercentiles in interface RankMorphology
      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.
      See Also:

    • meanBetweenPercentiles

      public Matrix<? extends UpdatablePArray> meanBetweenPercentiles(Matrix<? extends PArray> src, double fromPercentileIndex, double toPercentileIndex, Pattern pattern, double filler)
      Description copied from interface: RankMorphology
      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.

      Specified by:
      meanBetweenPercentiles in interface RankMorphology
      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.
      See Also:

    • meanBetweenValues

      public Matrix<? extends UpdatablePArray> meanBetweenValues(Matrix<? extends PArray> src, Matrix<? extends PArray> minValues, Matrix<? extends PArray> maxValues, Pattern pattern, double filler)
      Description copied from interface: RankMorphology
      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.

      Specified by:
      meanBetweenValues in interface RankMorphology
      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 RankMorphology.FILL_MIN_VALUE, RankMorphology.FILL_MAX_VALUE, RankMorphology.FILL_NEAREST_VALUE, which mean using of special calculation modes B, C, D.
      Returns:
      the mean between 2 given values of the source matrix.
      See Also:

    • mean

      public Matrix<? extends UpdatablePArray> mean(Matrix<? extends PArray> src, Pattern pattern)
      Description copied from interface: RankMorphology
      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
      Specified by:
      mean in interface RankMorphology
      Parameters:
      src - the source matrix.
      pattern - the pattern: the shape of the aperture.
      Returns:
      the mean of the source matrix.
      See Also:

    • functionOfSum

      public Matrix<? extends UpdatablePArray> functionOfSum(Matrix<? extends PArray> src, Pattern pattern, Func processingFunc)
      Description copied from interface: RankMorphology
      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 RankMorphology.mean(Matrix, Pattern).

      Specified by:
      functionOfSum in interface RankMorphology
      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.
      See Also:

    • functionOfPercentilePair

      public Matrix<? extends UpdatablePArray> functionOfPercentilePair(Matrix<? extends PArray> src, Matrix<? extends PArray> percentileIndexes1, Matrix<? extends PArray> percentileIndexes2, Pattern pattern, Func processingFunc)
      Description copied from interface: RankMorphology
      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 RankMorphology.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.

      Specified by:
      functionOfPercentilePair in interface RankMorphology
      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.
      See Also:

    • functionOfPercentilePair

      public Matrix<? extends UpdatablePArray> functionOfPercentilePair(Matrix<? extends PArray> src, double percentileIndex1, double percentileIndex2, Pattern pattern, Func processingFunc)
      Description copied from interface: RankMorphology
      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 RankMorphology.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.

      Specified by:
      functionOfPercentilePair in interface RankMorphology
      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.
      See Also:

    • percentile

      public void percentile(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Matrix<? extends PArray> percentileIndexes, Pattern pattern)
      Description copied from interface: RankMorphology
      Equivalent to RankMorphology.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 RankMorphology.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 RankMorphology.asPercentile(Matrix, Matrix, Pattern) and RankMorphology.percentile(Matrix, Matrix, Pattern) methods.

      Specified by:
      percentile in interface RankMorphology
      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.
      See Also:

    • percentile

      public void percentile(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, double percentileIndex, Pattern pattern)
      Description copied from interface: RankMorphology
      Equivalent to RankMorphology.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)
      Specified by:
      percentile in interface RankMorphology
      Parameters:
      dest - the target matrix.
      src - the source matrix.
      percentileIndex - r argument of the percentile.
      pattern - the pattern: the shape of the aperture.
      See Also:

    • rank

      public void rank(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> baseMatrix, Matrix<? extends PArray> rankedMatrix, Pattern pattern)
      Description copied from interface: RankMorphology
      Equivalent to RankMorphology.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.

      Specified by:
      rank in interface RankMorphology
      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.
      See Also:

    • meanBetweenPercentiles

      public void meanBetweenPercentiles(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Matrix<? extends PArray> fromPercentileIndexes, Matrix<? extends PArray> toPercentileIndexes, Pattern pattern, double filler)
      Description copied from interface: RankMorphology
      Equivalent to RankMorphology.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.

      Specified by:
      meanBetweenPercentiles in interface RankMorphology
      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.
      See Also:

    • meanBetweenPercentiles

      public void meanBetweenPercentiles(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, double fromPercentileIndex, double toPercentileIndex, Pattern pattern, double filler)
      Description copied from interface: RankMorphology
      Equivalent to RankMorphology.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.

      Specified by:
      meanBetweenPercentiles in interface RankMorphology
      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.
      See Also:

    • meanBetweenValues

      public void meanBetweenValues(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Matrix<? extends PArray> minValues, Matrix<? extends PArray> maxValues, Pattern pattern, double filler)
      Description copied from interface: RankMorphology
      Equivalent to RankMorphology.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.

      Specified by:
      meanBetweenValues in interface RankMorphology
      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 RankMorphology.FILL_MIN_VALUE, RankMorphology.FILL_MAX_VALUE, RankMorphology.FILL_NEAREST_VALUE, which mean using of special calculation modes B, C, D.
      See Also:

    • mean

      public void mean(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Pattern pattern)
      Description copied from interface: RankMorphology
      Equivalent to RankMorphology.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
      Specified by:
      mean in interface RankMorphology
      Parameters:
      dest - the target matrix.
      src - the source matrix.
      pattern - the pattern: the shape of the aperture.
      See Also:

    • functionOfSum

      public void functionOfSum(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Pattern pattern, Func processingFunc)
      Description copied from interface: RankMorphology
      Equivalent to RankMorphology.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 RankMorphology.mean(Matrix, Matrix, Pattern).

      Specified by:
      functionOfSum in interface RankMorphology
      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.
      See Also:

    • functionOfPercentilePair

      public void functionOfPercentilePair(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Matrix<? extends PArray> percentileIndexes1, Matrix<? extends PArray> percentileIndexes2, Pattern pattern, Func processingFunc)
      Description copied from interface: RankMorphology
      Equivalent to RankMorphology.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.

      Specified by:
      functionOfPercentilePair in interface RankMorphology
      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.
      See Also:

    • functionOfPercentilePair

      public void functionOfPercentilePair(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, double percentileIndex1, double percentileIndex2, Pattern pattern, Func processingFunc)
      Description copied from interface: RankMorphology
      Equivalent to RankMorphology.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.

      Specified by:
      functionOfPercentilePair in interface RankMorphology
      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.
      See Also: