Package net.algart.matrices.skeletons

Class ErodingSkeleton

java.lang.Object

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

net.algart.matrices.skeletons.ErodingSkeleton

All Implemented Interfaces:

ArrayProcessor, IterativeArrayProcessor<Matrix<? extends UpdatableBitArray>>

public class ErodingSkeleton
extends AbstractIterativeArrayProcessor<Matrix<? extends UpdatableBitArray>>
implements IterativeArrayProcessor<Matrix<? extends UpdatableBitArray>>

The simplest algorithm of multidimensional skeletonization of binary matrices, based on sequential erosions of the matrix by some small pattern.

More precisely, this class is an implementation of IterativeArrayProcessor interface, iteratively processing some bit matrix (Matrix(UpdatableBitArray)), named result and passed to the getInstance method. In this implementation:

• performIteration(ArrayContext) method calculates erosion(result,P) of the current result matrix by some small pattern P (usually little circle or square, in 2-dimensional case) and opening(result,Q,Morphology.SubtractionMode.NONE) of this matrix by some other pattern Q, usually equal to P or little greater than P. The opening is subtracted (in the set-theoretical sense) from the source result matrix and the difference (i.e. "thin" areas in the bit image) is united with the erosion (also in the set-theoretical sense). Then the result matrix is replaced with this union.
• done() method returns true if the last iteration was unable to change the matrix: all "objects" are already "thin" (removed after the erosion).
• result() method always returns the reference to the source matrix, passed to getInstance method.

The algorithm, implemented by this class, does not guarantee that connected "objects" (areas filled by 1 elements) stay connected and does not guarantee that the resulting "skeleton" will be "thin" enough. But it guarantees that resulting "skeleton" does not contain areas "larger" than the pattern Q used for opening operation.

This class is based on Matrices.asShifted method with some elementwise logical operations (AND, OR, NOT). So, the matrix is supposed to be infinitely pseudo-cyclically continued, as well Matrices.asShifted method supposes it. You can change this behavior by appending the source matrix with zero elements by calling Matrix.subMatrix(long[], long[], Matrix.ContinuationMode) method, where the dimensions of the "submatrix" are greater than dimensions of the source one by 1 and the continuationMode argument is Matrix.ContinuationMode.ZERO_CONSTANT.

This class can process a matrix with any number of dimensions.

This class is not thread-safe, but is thread-compatible and can be synchronized manually, if multithread access is necessary.

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 ErodingSkeleton	getInstance(ArrayContext context, Matrix<? extends UpdatableBitArray> matrix, Pattern erosionPattern, Pattern openingPattern)	Creates new instance of this class.
void	performIteration(ArrayContext context)	Performs the next iteration of the iterative algorithm.
Matrix<? extends UpdatableBitArray>	result()	Returns the result of the previous iteration.
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 ErodingSkeleton getInstance(ArrayContext context,
 Matrix<? extends UpdatableBitArray> matrix,
 Pattern erosionPattern,
 Pattern openingPattern)

Creates new instance of this class.

Parameters:

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

matrix - the bit matrix that should be processed and returned by result() method.

erosionPattern - the pattern that will be used for erosion operation at every iteration.

openingPattern - the pattern that will be used for opening operation at every iteration.

Returns:

new instance of this class.

Throws:

NullPointerException - if one of the arguments is null.

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

Specified by:

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

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

Specified by:

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

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

Specified by:

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

Returns:

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

result

public Matrix<? extends UpdatableBitArray> 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 UpdatableBitArray>>

Specified by:

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

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

Specified by:

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

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.