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:
current context
in the returned instance is equal
to the current context of the Morphology
object, passed to getInstance
methods.performIteration(ArrayContext)
method calculatesopening
(source_matrix,
Patterns.newMinkowskiSum
(ptn_{0},ptn_{1},...,ptn_{k}))
(k+1 summands),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.)
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 zerofilled (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 zerofilled 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.
context, memoryModel
Modifier and Type  Method and 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 builtin AlgART array, returned by
sumsOfOpenings() method. 
static IterativeOpening 
getInstance(Morphology morphology,
java.lang.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. 
java.lang.String 
toString()
Returns a brief string description of this object.

chain, context, limitIterations, part, process
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
chain, limitIterations, process
context
public static IterativeOpening getInstance(Morphology morphology, java.lang.Class<? extends UpdatablePArray> requiredType, Matrix<? extends PArray> matrix, Pattern... patterns)
result()
method.morphology
 the Morphology
object that will be used for performing openings.requiredType
 the type of builtin 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.java.lang.NullPointerException
 if one of arguments or one of passed patterns is null.java.lang.IllegalArgumentException
 if patterns.length==0 (no patterns passed).public static IterativeOpening getGranulometryInstance(Morphology morphology, Matrix<? extends PArray> matrix, Pattern... patterns)
sumsOfOpenings()
method.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.java.lang.NullPointerException
 if one of arguments or one of passed patterns is null.java.lang.IllegalArgumentException
 if patterns.length==0 (no patterns passed).public PNumberArray sumsOfOpenings()
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 ndimensional 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.public void performIteration(ArrayContext context)
IterativeArrayProcessor
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 arrayprocessing algorithm.
performIteration
in interface IterativeArrayProcessor<Matrix<? extends UpdatablePArray>>
performIteration
in class AbstractIterativeArrayProcessor<Matrix<? extends UpdatablePArray>>
context
 the context used by this instance for all operations; may be null.public boolean done()
IterativeArrayProcessor
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 arrayprocessing algorithm.
done
in interface IterativeArrayProcessor<Matrix<? extends UpdatablePArray>>
done
in class AbstractIterativeArrayProcessor<Matrix<? extends UpdatablePArray>>
public long estimatedNumberOfIterations()
IterativeArrayProcessor
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 arrayprocessing algorithm.
estimatedNumberOfIterations
in interface IterativeArrayProcessor<Matrix<? extends UpdatablePArray>>
estimatedNumberOfIterations
in class AbstractIterativeArrayProcessor<Matrix<? extends UpdatablePArray>>
public Matrix<? extends UpdatablePArray> result()
IterativeArrayProcessor
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 arrayprocessing algorithm.
result
in interface IterativeArrayProcessor<Matrix<? extends UpdatablePArray>>
result
in class AbstractIterativeArrayProcessor<Matrix<? extends UpdatablePArray>>
public void freeResources(ArrayContext context)
IterativeArrayProcessor
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 arrayprocessing algorithm.
freeResources
in interface IterativeArrayProcessor<Matrix<? extends UpdatablePArray>>
freeResources
in class AbstractIterativeArrayProcessor<Matrix<? extends UpdatablePArray>>
context
 the context of execution; may be null, then it will be ignored.public java.lang.String toString()
toString
in class java.lang.Object