Package net.algart.matrices.morphology

Class IterativeOpening

java.lang.Object

net.algart.arrays.AbstractIterativeArrayProcessor<Matrix<? extends UpdatablePArray>>

net.algart.matrices.morphology.IterativeOpening

All Implemented Interfaces:

ArrayProcessor, IterativeArrayProcessor<Matrix<? extends UpdatablePArray>>

public class IterativeOpening
extends AbstractIterativeArrayProcessor<Matrix<? extends UpdatablePArray>>
implements IterativeArrayProcessor<Matrix<? extends UpdatablePArray>>

Iterative opening of the matrix.

This class is an implementation of IterativeArrayProcessor interface, performing opening of some source matrix (Matrix(UpdatablePArray)) by sequential Minkowski multiples of some pattern: k⊗P, k=1,2,....

(In this class, the Morphology.opening method is supposed to be performed with the last argument Morphology.SubtractionMode.NONE.)

If the object was created by getInstance method, then every opening is added to some accumulator matrix, named result and returned by result() method. If the object was created by getGranulometryInstance method, then the arithmethic sum of all elements of every opening will be stored in some PNumberArray, returned by sumsOfOpenings() method. These sums contain information about typical sizes of objects, "drawn" in the matrix.

More precisely, in this implementation:

• the current context in the returned instance is equal to the current context of the Morphology object, passed to getInstance methods.
• performIteration(ArrayContext) method calculates
  opening(source_matrix, Patterns.newMinkowskiSum(ptn₀,ptn₁,...,ptn_k)) (k+1 summands),
  where k is the index of the current iteration (0, 1, 2, ...) and ptn_i=patterns[i%patterns.length], patterns is the argument of getInstance method. If only one pattern P was passed to getInstance method, it means the opening by Minkowski multiple pattern (k+1)⊗P. If the object was created by getInstance method, this opening is arithmetically added, with truncation of overflows, to the result matrix, by Matrices.applyFunc(ArrayContext, Func, Matrix, Matrix, Matrix) with Func.X_PLUS_Y function. If the object was created by getGranulometryInstance method, the arithmethic sum of all elements of this opening is added to the end of the AlgART array, returned by sumsOfOpenings() method. (Really, this method does not actually perform these operation, but performs equivalent calculations with some optimization.)
• Besides opening, this class always calculates the erosion by the same pattern. The done() method returns true if the last erosion was the same as the previous erosion. In this case, all further possible iteration will always generate the same opening. For bit matrices, it usually means that the opening is zero-filled (all "objects" were removed).
• result() method always returns the reference to the accumulator matrix result, if the object was created by getInstance method, or null, if the object was created by getGranulometryInstance method.

Note: this method is based on dilation method, called after erosion. It can be important for some continuation models of ContinuedMorphology class, if you use it as an argument of getInstance methods. For example, continuation by positive infinity constant work correctly for original opening method, but here it will lead to side effects as a result of dilation. We recommend not to use continuation by positive infinity or other high constants (greater than minimum of the source matrix).

The result matrix is created and zero-filled by getInstance method, and before the first iteration the source matrix is added to it (that means just copying). The AlgART array, returned by sumsOfOpenings() method, is created as empty MutablePNumberArray by getGranulometryInstance method, and before the first iteration the sum of elements of the source matrix is stored there as the first element.

Also note: there is no guarantees that result matrix, returned by result() method, and the array returned by sumsOfOpenings() method, are updated after each iteration. This class contains some optimization, that can lead to updating results only after some iteration, for example, after iteration #8, #16, etc. There is only the guarantee that result() and sumsOfOpenings() return valid results when done() returns true.

This class may be applied to a matrix with any number of dimensions.

Author:

Daniel Alievsky

Field Summary

Fields inherited from class net.algart.arrays.AbstractIterativeArrayProcessor

context, memoryModel

Method Summary

Modifier and Type	Method	Description
boolean	done()	Returns true if and only if the algorithm was successfully finished and there is no sense to perform further iterations.
long	estimatedNumberOfIterations()	Estimates the number of iterations, that should be performed from this moment to finish the algorithm.
void	freeResources(ArrayContext context)	If there are some resources, allocated by this object, which are not controlled by Java garbage collectors — files, streams, sockets, locks, etc. — this method tries to release them (for example, to close any files).
static IterativeOpening	getGranulometryInstance(Morphology morphology, Matrix<? extends PArray> matrix, Pattern... patterns)	Creates new instance of this class, that calculates the sum of all elements of every opening and stores them in some built-in AlgART array, returned by sumsOfOpenings() method.
static IterativeOpening	getInstance(Morphology morphology, Class<? extends UpdatablePArray> requiredType, Matrix<? extends PArray> matrix, Pattern... patterns)	Creates new instance of this class, that adds every opening to the accumulator matrix, returned by result() method.
void	performIteration(ArrayContext context)	Performs the next iteration of the iterative algorithm.
Matrix<? extends UpdatablePArray>	result()	Returns the result of the previous iteration.
PNumberArray	sumsOfOpenings()	Returns an immutable view of internal AlgART array, where the sums of all elements of the source matrix and every its openings are stored.
String	toString()	Returns a brief string description of this object.

Methods inherited from class net.algart.arrays.AbstractIterativeArrayProcessor

chain, context, limitIterations, part, process

Methods inherited from class java.lang.Object

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

Methods inherited from interface net.algart.arrays.ArrayProcessor

context

Methods inherited from interface net.algart.arrays.IterativeArrayProcessor

chain, limitIterations, process

Method Details

getInstance

public static IterativeOpening getInstance(Morphology morphology,
 Class<? extends UpdatablePArray> requiredType,
 Matrix<? extends PArray> matrix,
 Pattern... patterns)

Creates new instance of this class, that adds every opening to the accumulator matrix, returned by result() method.

Parameters:

morphology - the Morphology object that will be used for performing openings.

requiredType - the type of built-in AlgART array for result() matrix. Should be enough for storing elementwise sums of hundreds of opened matrices; in other case, overflows will lead to truncation of the sums.

matrix - the source matrix, that will be opened by Minkowski sums of the passed patterns (or just by Minkowski multiples k⊗P, if patterns argument contains only 1 pattern).

patterns - one or several patterns for performing erosion. For little pattern sizes, you may specify several patterns with near form to increase the precision of the resulting matrix.

Returns:

new instance of this class.

Throws:

NullPointerException - if one of arguments or one of passed patterns is null.

IllegalArgumentException - if patterns.length==0 (no patterns passed).

getGranulometryInstance

public static IterativeOpening getGranulometryInstance(Morphology morphology,
 Matrix<? extends PArray> matrix,
 Pattern... patterns)

Creates new instance of this class, that calculates the sum of all elements of every opening and stores them in some built-in AlgART array, returned by sumsOfOpenings() method.

Parameters:

morphology - the Morphology object that will be used for performing openings.

matrix - the source matrix, that will be opened by Minkowski sums of the passed patterns (or just by Minkowski multiples k⊗P, if patterns argument contains only 1 pattern).

patterns - one or several patterns for performing erosion. For little pattern sizes, you may specify several patterns with near form to increase the precision of the resulting matrix.

Returns:

new instance of this class.

Throws:

NullPointerException - if one of arguments or one of passed patterns is null.

IllegalArgumentException - if patterns.length==0 (no patterns passed).

sumsOfOpenings

public PNumberArray sumsOfOpenings()

Returns an immutable view of internal AlgART array, where the sums of all elements of the source matrix and every its openings are stored. The difference between elements #k and #k+1 estimates the summary area (volume, in 3D or n-dimensional cases) of all objects, which "sizes" are not "less" than the Minkowski sum of k patterns, but "less" than the Minkowski sum of k+1 patterns.

Returns:

an immutable view of the built-in AlgART array storing the sums of all elements of all openings.

performIteration

public void performIteration(ArrayContext context)

Description copied from interface: IterativeArrayProcessor

Performs the next iteration of the iterative algorithm. If the algorithm is IterativeArrayProcessor.done(), the results are unspecified: please never call this method if IterativeArrayProcessor.done() returns true.

You usually don't need to call this method: please call IterativeArrayProcessor.process() instead. If you need to perform only one or n iterations, you may use limitIterations(n) call.

Warning: this method should ignore the current execution context of this object. Instead, this method should use the context of execution specified by context argument. This method is called by IterativeArrayProcessor.process() method with the argument, describing a subtrask of the full algorithm. The context argument may be null: this method should work properly in this case (ignore the context).

This method must be implemented while creating a new iterative array-processing algorithm.

Specified by:

performIteration in interface IterativeArrayProcessor<Matrix<? extends UpdatablePArray>>

Specified by:

performIteration in class AbstractIterativeArrayProcessor<Matrix<? extends UpdatablePArray>>

Parameters:

context - the context used by this instance for all operations; may be null.

done

public boolean done()

Description copied from interface: IterativeArrayProcessor

Returns true if and only if the algorithm was successfully finished and there is no sense to perform further iterations.

This method usually does not perform actual calculations and works very quickly (just returns and internal flag). However, this condition is not strict.

You usually don't need to call this method: it is automatically called by IterativeArrayProcessor.process() method.

This method must be implemented while creating a new iterative array-processing algorithm.

Specified by:

done in interface IterativeArrayProcessor<Matrix<? extends UpdatablePArray>>

Specified by:

done in class AbstractIterativeArrayProcessor<Matrix<? extends UpdatablePArray>>

Returns:

true if and only if the algorithm was successfully finished.

estimatedNumberOfIterations

public long estimatedNumberOfIterations()

Description copied from interface: IterativeArrayProcessor

Estimates the number of iterations, that should be performed from this moment to finish the algorithm. Returns 0 if it is impossible or too difficult to estimate this number: it means that the remaining number of iteration is unknown.

This method may require some time for its execution.

You usually don't need to call this method: it is automatically called from time to time by IterativeArrayProcessor.process() method. It is used for creating subcontexts, describing a part of the full task.

This method must be implemented while creating a new iterative array-processing algorithm.

Specified by:

estimatedNumberOfIterations in interface IterativeArrayProcessor<Matrix<? extends UpdatablePArray>>

Specified by:

estimatedNumberOfIterations in class AbstractIterativeArrayProcessor<Matrix<? extends UpdatablePArray>>

Returns:

the estimated number of iterations, that should be performed from this moment to finish the algorithm.

result

public Matrix<? extends UpdatablePArray> result()

Description copied from interface: IterativeArrayProcessor

Returns the result of the previous iteration. Usually it is UpdatableArray or Matrix<? extends UpdatableArray>. This method returns valid result even if no iterations were performed yet. If IterativeArrayProcessor.done() method returns true, the result of this method is the final result of iterative processing performed by this instance.

This method may return null. In this case, the concrete implementation of this interface should provide additional methods for returning calculation results.

This method does not perform actual calculations and works very quickly.

This method must be implemented while creating a new iterative array-processing algorithm.

Specified by:

result in interface IterativeArrayProcessor<Matrix<? extends UpdatablePArray>>

Specified by:

result in class AbstractIterativeArrayProcessor<Matrix<? extends UpdatablePArray>>

Returns:

the result of the previous iteration (may be null).

freeResources

public void freeResources(ArrayContext context)

Description copied from interface: IterativeArrayProcessor

If there are some resources, allocated by this object, which are not controlled by Java garbage collectors — files, streams, sockets, locks, etc. — this method tries to release them (for example, to close any files). The object stays alive: if the resources will be necessary for following operations, they will be automatically re-acquired.

Usually, this method just calls Array.freeResources(context) and Matrix.freeResources(context) for all temporary arrays and matrices, allocated by this object for storing work data.

If IterativeArrayProcessor.result() method returns AlgART array or matrix (typical situation), this method calls Array.freeResources(context) / Matrix.freeResources(context) methods for this array / matrix.

This method may be used in situations when the instance of this object has long time life and will be reused in future.

This method must be implemented while creating a new iterative array-processing algorithm.

Specified by:

freeResources in interface IterativeArrayProcessor<Matrix<? extends UpdatablePArray>>

Specified by:

freeResources in class AbstractIterativeArrayProcessor<Matrix<? extends UpdatablePArray>>

Parameters:

context - the context of execution; may be null, then it will be ignored.

toString

public String toString()

Returns a brief string description of this object.

Overrides:

toString in class Object

Returns:

a brief string description of this object.