Package net.algart.matrices.morphology

Class BasicRankMorphology

java.lang.Object

net.algart.arrays.AbstractArrayProcessorWithContextSwitching

net.algart.matrices.morphology.AbstractMorphology

net.algart.matrices.morphology.AbstractRankMorphology

net.algart.matrices.morphology.BasicRankMorphology

All Implemented Interfaces:

Cloneable, ArrayProcessor, ArrayProcessorWithContextSwitching, Morphology, RankMorphology

public abstract class BasicRankMorphology
extends AbstractRankMorphology
implements RankMorphology

Almost complete implementation of RankMorphology interface with an instantiation method of some complete implementation.

This class fully implements all methods, declared in RankMorphology interface, according to the detailed specifications listed in the comments to that interface. The only methods, which stay abstract here, are the following 3 methods of AbstractMorphology superclass:

• AbstractRankMorphology.context(ArrayContext newContext),
• asDilationOrErosion(Matrix src, Pattern pattern, boolean isDilation),
• dilationOrErosion(Matrix dest, Matrix src, Pattern pattern, boolean isDilation, boolean disableMemoryAllocation).

All other methods are implemented via the simple calls of asProcessed and process method of the corresponding streaming aperture processors, listed in RankProcessors class.

This package provides some concrete complete inheritor, which implements also these 3 methods. This inheritor is instantiated by the following method:

• getInstance(ArrayContext, double, CustomRankPrecision).

But you can also inherit this class yourself and implement dilation and erosion (the basic operations of the mathematical morphology) in other way.

Author:

Daniel Alievsky

Nested Class Summary

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

Morphology.SubtractionMode

Field Summary

Fields inherited from interface net.algart.matrices.morphology.RankMorphology

FILL_MAX_VALUE, FILL_MIN_VALUE, FILL_NEAREST_VALUE

Method Summary

Modifier and Type	Method	Description
protected abstract Matrix<? extends PArray>	asDilationOrErosion(Matrix<? extends PArray> src, Pattern pattern, boolean isDilation)	This method must be equivalent to AbstractMorphology.asDilation(Matrix src, Pattern pattern) if isDilation argument is true or to AbstractMorphology.asErosion(Matrix src, Pattern pattern) if isDilation argument is false.
Matrix<? extends PArray>	asFunctionOfPercentilePair(Matrix<? extends PArray> src, Matrix<? extends PArray> percentilesIndexes1, Matrix<? extends PArray> percentilesIndexes2, Pattern pattern, Func processingFunc)	Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the result of some given function f(v, v1,v2) of the source matrix v and two percentiles v1,v2 of the source matrix by the specified pattern.
Matrix<? extends PArray>	asFunctionOfSum(Matrix<? extends PArray> src, Pattern pattern, Func processingFunc)	Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the result of some given function f(S) of the aperture sum S of the source matrix by the specified pattern.
Matrix<? extends PArray>	asMeanBetweenPercentiles(Matrix<? extends PArray> src, Matrix<? extends PArray> fromPercentilesIndexes, Matrix<? extends PArray> toPercentilesIndexes, Pattern pattern, double filler)	Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the mean between 2 percentiles of the source matrix by the specified pattern.
Matrix<? extends PArray>	asMeanBetweenValues(Matrix<? extends PArray> src, Matrix<? extends PArray> minValues, Matrix<? extends PArray> maxValues, Pattern pattern, double filler)	Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the mean between 2 values of the source matrix by the specified pattern.
Matrix<? extends PArray>	asPercentile(Matrix<? extends PArray> src, Matrix<? extends PArray> percentileIndexes, Pattern pattern)	Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the percentile of the source matrix by the specified pattern.
<T extends PArray> Matrix<T>	asRank(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.
protected abstract Matrix<? extends UpdatablePArray>	dilationOrErosion(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Pattern pattern, boolean isDilation, boolean disableMemoryAllocation)	This method must be equivalent to AbstractMorphology.dilation(Matrix dest, Matrix src, Pattern pattern, boolean disableMemoryAllocation) if isDilation argument is true or to AbstractMorphology.erosion(Matrix dest, Matrix src, Pattern pattern, boolean disableMemoryAllocation) if isDilation argument is false.
void	functionOfPercentilePair(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Matrix<? extends PArray> percentilesIndexes1, Matrix<? extends PArray> percentilesIndexes2, Pattern pattern, Func processingFunc)	Equivalent to RankMorphology.functionOfPercentilePair(Matrix, Matrix, Matrix, Pattern, Func) method, but the result matrix will be placed in the dest argument.
void	functionOfSum(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Pattern pattern, Func processingFunc)	Equivalent to RankMorphology.functionOfSum(Matrix, Pattern, Func) method, but the result matrix will be placed in the dest argument.
static RankMorphology	getInstance(ArrayContext context, double dilationLevel, CustomRankPrecision precision)	Returns new instance of some inheritor of this class, implementing dilation and erosion operations via the percentiles.
boolean	isPseudoCyclic()	Returns true, if this class works in the default pseudo-cyclic continuation mode.
void	meanBetweenPercentiles(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Matrix<? extends PArray> fromPercentilesIndexes, Matrix<? extends PArray> toPercentilesIndexes, Pattern pattern, double filler)	Equivalent to RankMorphology.meanBetweenPercentiles(Matrix, Matrix, Matrix, Pattern, double) method, but the result matrix will be placed in the dest argument.
void	meanBetweenValues(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Matrix<? extends PArray> minValues, Matrix<? extends PArray> maxValues, Pattern pattern, double filler)	Equivalent to RankMorphology.meanBetweenValues(Matrix, Matrix, Matrix, Pattern, double) method, but the result matrix will be placed in the dest argument.
void	percentile(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, Matrix<? extends PArray> percentileIndexes, Pattern pattern)	Equivalent to RankMorphology.percentile(Matrix, Matrix, Pattern) method, but the result matrix will be placed in the dest argument.
void	rank(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> baseMatrix, Matrix<? extends PArray> rankedMatrix, Pattern pattern)	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).

Methods inherited from class net.algart.matrices.morphology.AbstractRankMorphology

asFunctionOfPercentilePair, asMean, asMeanBetweenPercentiles, asPercentile, constantPercentileMatrix, context, functionOfPercentilePair, functionOfPercentilePair, functionOfPercentilePair, functionOfSum, mean, mean, meanBetweenPercentiles, meanBetweenPercentiles, meanBetweenPercentiles, meanBetweenValues, percentile, percentile, percentile, rank

Methods inherited from class net.algart.matrices.morphology.AbstractMorphology

asDilation, asErosion, beucherGradient, closing, dilation, dilation, dilation, dilation, dilationErosion, dimensionsAllowed, erosion, erosion, erosion, erosion, erosionDilation, maskedDilationErosion, maskedErosionDilation, opening, weakDilation, weakErosion

Methods inherited from class net.algart.arrays.AbstractArrayProcessorWithContextSwitching

context, contextPart, memoryModel

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.algart.arrays.ArrayProcessor

context

Methods inherited from interface net.algart.matrices.morphology.Morphology

asDilation, asErosion, beucherGradient, closing, dilation, dilation, dilation, dilation, dilationErosion, erosion, erosion, erosion, erosion, erosionDilation, maskedDilationErosion, maskedErosionDilation, opening, weakDilation, weakErosion

Methods inherited from interface net.algart.matrices.morphology.RankMorphology

asFunctionOfPercentilePair, asMean, asMeanBetweenPercentiles, asPercentile, context, functionOfPercentilePair, functionOfPercentilePair, functionOfPercentilePair, functionOfSum, mean, mean, meanBetweenPercentiles, meanBetweenPercentiles, meanBetweenPercentiles, meanBetweenValues, percentile, percentile, percentile, rank

Method Details

getInstance

public static RankMorphology getInstance(ArrayContext context,
 double dilationLevel,
 CustomRankPrecision precision)

Returns new instance of some inheritor of this class, implementing dilation and erosion operations via the percentiles. Namely, in the created object dilation(m,pattern) method is equivalent to percentile(m,dilationLevel*N,pattern) and erosion(m,pattern) method is equivalent to percentile(m,dilationLevel*N,pattern.symmetric()), where N=pattern.pointCount()-1 and dilationLevel is the argument of this method. This argument must be in range 0.0 ≤ dilationLevel ≤ 1.0.

More precisely, in the created object the methods

1. asDilationOrErosion(Matrix src, Pattern pattern, boolean isDilation) and
2. dilationOrErosion(Matrix dest, Matrix src, Pattern pattern, boolean isDilation, boolean disableMemoryAllocation)

work in the following way.

Let the double value r be r=dilationLevel*(pattern.pointCount()-1) in a case of dilation (isDilation argument is true) or r=(1.0-dilationLevel)*(pattern.pointCount()-1) in a case of erosion (isDilation argument is false). Then, let index be:

• this double value index=r, if the element type of the source matrix src is float or double or if we are using the precise histogram model (precision.interpolated() is true);
• or the rounded (long) integer value index=Math.round(r), if the source matrix is fixed-point and we are using the simple histogram model (precision.interpolated() is false).

At last, let P be pattern in a case of dilation (isDilation argument is true) or pattern.symmetric() in a case of erosion (isDilation argument is false).

Then, in the returned object the 1st method asDilationOrErosion is equivalent to asPercentile(src,index,P) and the 2nd method dilationOrErosion is equivalent to percentile(dest,src,index,P). (The disableMemoryAllocation argument of dilationOrErosion method is ignored by this implementation.)

Please note: using Math.round for rounding the percentile index does not correspond to the standard behaviour of integer percentiles, which are rounded, in a case of the precise histogram model, according more complicated rules (see comments to RankMorphology.percentile(Matrix, Matrix, Pattern) and Histogram.iPreciseValue(long[], double) methods). So, this method does not try to round the real percentile index r in the precise histogram model. But in the simple histogram model, when the element type is fixed-point and some form of rounding is required in any case, this method calls Math.round — it provides better "symmetry" between dilation and erosion operations.

The precise behaviour of all methods of RankMorphology interface in the returned object depends on precision object: see comments to CustomRankPrecision and RankMorphology.

Parameters:

context - the context that will be used by this object; may be null, then it will be ignored.

dilationLevel - the level: 1.0 means strict dilation and erosion as described in Morphology interface, 0.5 means median, 0.0 means that dilation works like erosion and erosion works like dilation (but with a symmetric pattern).

precision - precision characteristics of all rank operations, performed by the created object.

Returns:

new instance of this class.

Throws:

NullPointerException - if precision argument is null

IllegalArgumentException - if the dilationLevel argument is out of 0.0..1.0 range of if bitLevels=precision.bitLevels() are incorrect: bitLevels.length==0, or if bitLevels.length>31, or if some of elements bitLevels is not in 1..30 range, or if bitLevels[k]>=bitLevels[k+1] for some k.

isPseudoCyclic

public boolean isPseudoCyclic()

Description copied from interface: Morphology

Returns true, if this class works in the default pseudo-cyclic continuation mode.

More precisely, it means that when the value in some element of the processed matrix, returned by a method of this class, depends on elements of the source matrix, lying outside its bounds, then it is supposed that the values outside the source matrix are calculated as described in Matrix.ContinuationMode.PSEUDO_CYCLIC. Exactly such behaviour is specified in the comments to the basic Morphology.dilation(Matrix, Pattern) and Morphology.erosion(Matrix, Pattern) methods as the default definition of dilation and erosion.

This method returns true in BasicMorphology and BasicRankMorphology implementation. However, it usually returns false in ContinuedMorphology and ContinuedRankMorphology classes — excepting the only degenerated case when the used continuation mode is PSEUDO_CYCLIC.

Specified by:

isPseudoCyclic in interface Morphology

Specified by:

isPseudoCyclic in class AbstractMorphology

Returns:

whether this class works in the pseudo-cyclic continuation mode.

asDilationOrErosion

protected abstract Matrix<? extends PArray> asDilationOrErosion(Matrix<? extends PArray> src,
 Pattern pattern,
 boolean isDilation)

Description copied from class: AbstractMorphology

This method must be equivalent to AbstractMorphology.asDilation(Matrix src, Pattern pattern) if isDilation argument is true or to AbstractMorphology.asErosion(Matrix src, Pattern pattern) if isDilation argument is false.

The implementations of those methods, provided by this class, just call this method with corresponding isDilation argument.

Specified by:

asDilationOrErosion in class AbstractRankMorphology

Parameters:

src - the source matrix.

pattern - the pattern.

isDilation - what should return this method: dilation or erosion.

Returns:

the "lazy" matrix containing the dilation or erosion of the source matrix.

dilationOrErosion

protected abstract Matrix<? extends UpdatablePArray> dilationOrErosion(Matrix<? extends UpdatablePArray> dest,
 Matrix<? extends PArray> src,
 Pattern pattern,
 boolean isDilation,
 boolean disableMemoryAllocation)

Description copied from class: AbstractMorphology

This method must be equivalent to AbstractMorphology.dilation(Matrix dest, Matrix src, Pattern pattern, boolean disableMemoryAllocation) if isDilation argument is true or to AbstractMorphology.erosion(Matrix dest, Matrix src, Pattern pattern, boolean disableMemoryAllocation) if isDilation argument is false. There is the only little difference: if dest argument is null, this methods does not throw NullPointerException, but allocates new matrix with the same dimensions and element type as src and use it for storing the result. The result (newly created matrix or non-null dest argument) is returned as the result of this method.

The implementations of AbstractMorphology.dilation(Matrix dest, Pattern pattern), AbstractMorphology.erosion(Matrix dest, Pattern pattern), AbstractMorphology.dilation(Matrix dest, Matrix src, Pattern pattern, boolean disableMemoryAllocation), AbstractMorphology.erosion(Matrix dest, Matrix src, Pattern pattern, boolean disableMemoryAllocation) methods, provided by this class, just call this method with corresponding isDilation argument and with dest==null in a case of first two methods.

The implementation of this method, provided by AbstractMorphology class, just copies the result of AbstractMorphology.asDilationOrErosion(Matrix, Pattern, boolean) asDilationOrErosion} method to dest matrix:

 Matrices.copy(context, castDest, AbstractMorphology.asDilationOrErosion(Matrix, Pattern, boolean)
 asDilationOrErosion}(src, pattern, isDilation));

where castDest is dest if dest.elementType()==src.elementType(), the newly created matrix if dest==null or the dest matrix, cast to the necessary element type, if the source and destination element types are different:

 Matrices.asUpdatableFuncMatrix(true, Func.UPDATABLE_IDENTITY, src.updatableType(UpdatablePArray.class), dest)
 

The implementations of this method in the inheritors usually provide better algorithms, especially if disableMemoryAllocation argument is false.

Specified by:

dilationOrErosion in class AbstractRankMorphology

Parameters:

dest - the target matrix (or null for creating a new matrix).

src - the source matrix.

pattern - the pattern.

isDilation - what should perform this method: dilation or erosion.

disableMemoryAllocation - if false, this method may allocate additional temporary matrices for optimizing the algorithm speed; if true, no any work memory will be allocated.

Returns:

the reference to dest argument if it is not null, newly allocated resulting matrix in other case.

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

Specified by:

asPercentile in class AbstractRankMorphology

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:

• RankMorphology.asPercentile(Matrix, double, Pattern)
• RankMorphology.percentile(Matrix, Matrix, Pattern)
• RankMorphology.percentile(Matrix, Matrix, Matrix, Pattern)

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

Specified by:

percentile in class AbstractRankMorphology

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:

• RankMorphology.percentile(Matrix, Matrix, double, Pattern)
• RankMorphology.asPercentile(Matrix, Matrix, Pattern)
• RankMorphology.percentile(Matrix, Matrix, Pattern)

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 2¹⁶=65536 or 2⁸=256, it is enough to specify correspondingly requiredType=ShortArray.class or ByteArray.class.

Specified by:

asRank in interface RankMorphology

Specified by:

asRank in class AbstractRankMorphology

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:

• RankMorphology.rank(Class, Matrix, Matrix, Pattern)
• RankMorphology.rank(Matrix, Matrix, Matrix, Pattern)

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 2¹⁶=65536 or 2⁸=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

Specified by:

rank in class AbstractRankMorphology

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:

• RankMorphology.asRank(Class, Matrix, Matrix, Pattern)
• RankMorphology.rank(Class, Matrix, Matrix, Pattern)

asMeanBetweenPercentiles

public Matrix<? extends PArray> asMeanBetweenPercentiles(Matrix<? extends PArray> src,
 Matrix<? extends PArray> fromPercentilesIndexes,
 Matrix<? extends PArray> toPercentilesIndexes,
 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 r₁ and r₂ 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

Specified by:

asMeanBetweenPercentiles in class AbstractRankMorphology

Parameters:

src - the source matrix.

fromPercentilesIndexes - the matrix containing r₁ argument: the indexes of the less percentile of the averaged range for every element of the result.

toPercentilesIndexes - the matrix containing r₂ 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 r₁≥r₂.

Returns:

the "lazy" matrix containing the mean between 2 given percentiles of the source matrix.

See Also:

• RankMorphology.asMeanBetweenPercentiles(Matrix, double, double, Pattern, double)
• RankMorphology.meanBetweenPercentiles(Matrix, Matrix, Matrix, Pattern, double)
• RankMorphology.meanBetweenPercentiles(Matrix, Matrix, Matrix, Matrix, Pattern, double)

meanBetweenPercentiles

public void meanBetweenPercentiles(Matrix<? extends UpdatablePArray> dest,
 Matrix<? extends PArray> src,
 Matrix<? extends PArray> fromPercentilesIndexes,
 Matrix<? extends PArray> toPercentilesIndexes,
 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

Specified by:

meanBetweenPercentiles in class AbstractRankMorphology

Parameters:

dest - the target matrix.

src - the source matrix.

fromPercentilesIndexes - the matrix containing r₁ argument: the indexes of the less percentile of the averaged range for every element of the result.

toPercentilesIndexes - the matrix containing r₂ 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 r₁≥r₂.

See Also:

• RankMorphology.meanBetweenPercentiles(Matrix, Matrix, double, double, Pattern, double)
• RankMorphology.asMeanBetweenPercentiles(Matrix, Matrix, Matrix, Pattern, double)
• RankMorphology.meanBetweenPercentiles(Matrix, Matrix, Matrix, Pattern, double)

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 v₁ and v₂ 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(v₁*σ)≥r(v₂*σ)) are specified by the last filler argument of this method:

• if filler argument is RankMorphology.FILL_MIN_VALUE (Double.NEGATIVE_INFINITY), the mode B is used;
• if filler argument is RankMorphology.FILL_MAX_VALUE (Double.POSITIVE_INFINITY), the mode C is used;
• if filler argument is RankMorphology.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.

Specified by:

asMeanBetweenValues in interface RankMorphology

Specified by:

asMeanBetweenValues in class AbstractRankMorphology

Parameters:

src - the source matrix.

minValues - the matrix containing v₁ argument: the low bound of the averaged range of values for every element of the result.

maxValues - the matrix containing v₂ 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(v₁*σ)≥r(v₂*σ), 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:

• RankMorphology.meanBetweenValues(Matrix, Matrix, Matrix, Pattern, double)
• RankMorphology.meanBetweenValues(Matrix, Matrix, Matrix, Matrix, Pattern, double)

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

Specified by:

meanBetweenValues in class AbstractRankMorphology

Parameters:

dest - the target matrix.

src - the source matrix.

minValues - the matrix containing v₁ argument: the low bound of the averaged range of values for every element of the result.

maxValues - the matrix containing v₂ 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(v₁*σ)≥r(v₂*σ), 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:

• RankMorphology.asMeanBetweenValues(Matrix, Matrix, Matrix, Pattern, double)
• RankMorphology.meanBetweenValues(Matrix, Matrix, Matrix, Pattern, double)

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

Specified by:

asFunctionOfSum in class AbstractRankMorphology

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:

• RankMorphology.functionOfSum(Matrix, Pattern, Func)
• RankMorphology.functionOfSum(Matrix, Matrix, Pattern, Func)

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

Specified by:

functionOfSum in class AbstractRankMorphology

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:

• RankMorphology.asFunctionOfSum(Matrix, Pattern, Func)
• RankMorphology.functionOfSum(Matrix, Pattern, Func)

asFunctionOfPercentilePair

public Matrix<? extends PArray> asFunctionOfPercentilePair(Matrix<? extends PArray> src,
 Matrix<? extends PArray> percentilesIndexes1,
 Matrix<? extends PArray> percentilesIndexes2,
 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, v₁,v₂) of the source matrix v and two percentiles v₁,v₂ 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 v₁) or percentileIndexes2 matrix (for v₂). 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,v₁,v₂), 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 v₁ and v₂ of the source matrix and returns processingFunc.get(v,v₁,v₂) 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

Specified by:

asFunctionOfPercentilePair in class AbstractRankMorphology

Parameters:

src - the source matrix.

percentilesIndexes1 - the 1st matrix containing r argument: the indexes of the 1st percentile v₁ for every element of the result.

percentilesIndexes2 - the 2nd matrix containing r argument: the indexes of the 2nd percentile v₂ 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,v₁,v₂), where v is the element of the source matrix, v₁ and v₂ are the corresponding percentiles.

Returns:

the "lazy" matrix containing the result of the given function.

See Also:

• RankMorphology.asFunctionOfPercentilePair(Matrix, double, double, Pattern, Func)
• RankMorphology.functionOfPercentilePair(Matrix, Matrix, Matrix, Pattern, Func)
• RankMorphology.functionOfPercentilePair(Matrix, Matrix, Matrix, Matrix, Pattern, Func)

functionOfPercentilePair

public void functionOfPercentilePair(Matrix<? extends UpdatablePArray> dest,
 Matrix<? extends PArray> src,
 Matrix<? extends PArray> percentilesIndexes1,
 Matrix<? extends PArray> percentilesIndexes2,
 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

Specified by:

functionOfPercentilePair in class AbstractRankMorphology

Parameters:

dest - the target matrix.

src - the source matrix.

percentilesIndexes1 - the 1st matrix containing r argument: the indexes of the 1st percentile v₁ for every element of the result.

percentilesIndexes2 - the 2nd matrix containing r argument: the indexes of the 2nd percentile v₂ 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,v₁,v₂), where v is the element of the source matrix, v₁ and v₂ are the corresponding percentiles.

See Also:

• RankMorphology.functionOfPercentilePair(Matrix, Matrix, double, double, Pattern, Func)
• RankMorphology.asFunctionOfPercentilePair(Matrix, Matrix, Matrix, Pattern, Func)
• RankMorphology.functionOfPercentilePair(Matrix, Matrix, Matrix, Pattern, Func)