Package net.algart.matrices.morphology

Class BasicMorphology

java.lang.Object

net.algart.arrays.AbstractArrayProcessorWithContextSwitching

net.algart.matrices.morphology.AbstractMorphology

net.algart.matrices.morphology.BasicMorphology

All Implemented Interfaces:

Cloneable, ArrayProcessor, ArrayProcessorWithContextSwitching, Morphology

public class BasicMorphology
extends AbstractMorphology
implements Morphology

The simplest complete implementation of Morphology interface. This implementation complies with the strict definition of dilation and erosion specified in comments to Morphology.dilation(Matrix, Pattern) and Morphology.erosion(Matrix, Pattern) methods.

This class provides essential optimization for non-"lazy" dilation and erosion, performed by Morphology.dilation(Matrix, Pattern) and Morphology.erosion(Matrix, Pattern) methods, for most types of patterns. So, usually you should use these method, but not Morphology.asDilation(Matrix, Pattern) and Morphology.asErosion(Matrix, Pattern).

Some methods of the returned object can throw TooLargeArrayException in a very improbable situation when the source matrix length (number of elements) is greater than Long.MAX_VALUE/2=2⁶²-1.

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

Author:

Daniel Alievsky

Nested Class Summary

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

Morphology.SubtractionMode

Method Summary

Modifier and Type	Method	Description
protected 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.
protected 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.
protected boolean	dimensionsAllowed(Matrix<? extends PArray> matrix, Pattern pattern)
static BasicMorphology	getInstance(ArrayContext context)	Equivalent to getInstance(context, Arrays.SystemSettings.maxTempJavaMemory()).
static BasicMorphology	getInstance(ArrayContext context, long maxTempJavaMemory)	Returns new instance of this class.
boolean	isPseudoCyclic()	Returns true, if this class works in the default pseudo-cyclic continuation mode.

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

asDilation, asErosion, beucherGradient, closing, context, dilation, dilation, dilation, dilation, dilationErosion, 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, context, dilation, dilation, dilation, dilation, dilationErosion, erosion, erosion, erosion, erosion, erosionDilation, maskedDilationErosion, maskedErosionDilation, opening, weakDilation, weakErosion

Method Details

getInstance

public static BasicMorphology getInstance(ArrayContext context)

Equivalent to getInstance(context, Arrays.SystemSettings.maxTempJavaMemory()).

Parameters:

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

Returns:

new instance of this class.

getInstance

public static BasicMorphology getInstance(ArrayContext context,
 long maxTempJavaMemory)

Returns new instance of this class.

The maxTempJavaMemory argument specifies the maximal amount of usual Java memory, in bytes, that methods of this class may freely use for internal needs and for creating results. It means: if the size of the resulting matrix, or some temporary matrix or array (or, maybe, the summary size of several temporary matrices) is not greater than this limit, then a method may (though not must) use SimpleMemoryModel for creating such AlgART matrices (arrays) or may allocate usual Java arrays. For allocating greater amount of memory, all methods should use, when possible, the memory model specified by the context: ArrayContext.getMemoryModel().

Parameters:

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

maxTempJavaMemory - maximal amount of Java memory, in bytes, allowed for allocating by methods of this class.

Returns:

new instance of this class.

Throws:

IllegalArgumentException - if the maxTempJavaMemory argument is negative.

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 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 AbstractMorphology

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 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.

Overrides:

dilationOrErosion in class AbstractMorphology

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.

dimensionsAllowed

protected boolean dimensionsAllowed(Matrix<? extends PArray> matrix,
 Pattern pattern)

Overrides:

dimensionsAllowed in class AbstractMorphology