Package net.algart.matrices.skeletons

Class WeakOctupleThinningSkeleton2D

java.lang.Object
net.algart.arrays.AbstractIterativeArrayProcessor<Matrix<? extends UpdatableBitArray>>
net.algart.matrices.skeletons.WeakOctupleThinningSkeleton2D
All Implemented Interfaces:
ArrayProcessor, IterativeArrayProcessor<Matrix<? extends UpdatableBitArray>>, ThinningSkeleton
public class WeakOctupleThinningSkeleton2D extends AbstractIterativeArrayProcessor<Matrix<? extends UpdatableBitArray>> implements ThinningSkeleton

Weaker version of OctupleThinningSkeleton2D skeletonization algorithm.

This class implements almost the same algorithm as OctupleThinningSkeleton2D, but the thinning methods are not so aggressive. This class also guarantees that 8-connected "objects" (areas filled by 1 elements) always stay 8-connected: see ThinningSkeleton interface about the precise sense of this state.

The lines of the skeleton can be more even, than in OctupleThinningSkeleton2D, but some additional "bad" cases will not be thinned until 1-pixel thickness. For example:

 . . . . . 1 . . .      . . . . . 1 . . .
 . . . . . 1 . . .      . . . . . 1 . . .
 . . . . . 1 . . .      . . . . . 1 . . .
 . 1 1 1 1 1 . . .      . 1 1 1 1 1 1 1 .
 . . . . 1 1 1 1 1      . . . . 1 . . . .
 . . . . 1 . . . .      . . . . 1 . . . .
 . . . . 1 . . . .      . . . . 1 . . . .
 . . . . 1 . . . .      . . . . . . . . .

These objects cannot be thinned by this algorithm. Unlike this, OctupleThinningSkeleton2D transforms them to the following (or similar) skeletons:

 . . . . . 1 . . .      . . . . . 1 . . .
 . . . . . 1 . . .      . . . . . 1 . . .
 . . . . . 1 . . .      . . . . . 1 . . .
 . 1 1 1 1 . . . .      . 1 1 1 . 1 1 1 .
 . . . . . 1 1 1 1      . . . . 1 . . . .
 . . . . 1 . . . .      . . . . 1 . . . .
 . . . . 1 . . . .      . . . . 1 . . . .
 . . . . 1 . . . .      . . . . . . . . .

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 may be applied to a matrix with any number of dimensions, but it is designed for 2-dimensional case: all other dimensions will be ignored.

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

Author:
Daniel Alievsky

  • Method Details

    • getInstance

      public static WeakOctupleThinningSkeleton2D getInstance(ArrayContext context, Matrix<? extends UpdatableBitArray> matrix, boolean straightThinning, boolean diagonalThinning, boolean topological)
      Creates new instance of this class.

      If the straightThinning or diagonalThinning argument is false, the algorithm will skip thinning, correspondingly, along the axes or along diagonal directions. Note that the results will usually be incorrect: large object will stay not skeletonized. (Compare with diagonalThinning argument in OctupleThinningSkeleton2D.getInstance(ArrayContext, Matrix, boolean, boolean).)

      If the topological is true, the algorithm doesn't stop when all objects in the matrix become "thin" (1-pixel thickness), but continues shortening all "free ends" of all skeleton lines, while there is at least one "free end". As a result, objects that have no "holes" will be removed at all, objects that have 1 hole will be transformed into 1-pixel closed line ("ring"), etc. This mode essentially slows down the algorithm.

      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 IterativeArrayProcessor.result() method.
      straightThinning - whether the algorithm will perform thinning along x- and y-axes; usually true.
      diagonalThinning - whether the algorithm will perform diagonal thinning; usually true.
      topological - whether the algorithm will shorten isolated thin lines with "free ends".
      Returns:
      new instance of this class.
      Throws:
      NullPointerException - if matrix argument is null.

    • getInstance

      public static WeakOctupleThinningSkeleton2D getInstance(ArrayContext context, Matrix<? extends UpdatableBitArray> matrix)
      Creates new instance of this class. Equivalent to getInstance(context, matrix, true, true, false).
      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 IterativeArrayProcessor.result() method.
      Returns:
      new instance of this class.
      Throws:
      NullPointerException - if matrix argument is null.

    • 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>>
      Returns:
      the estimated number of iterations, that should be performed from this moment to finish the algorithm.

    • asThinning

      public Matrix<BitArray> asThinning(int directionIndex)
      Returns current result() matrix thinned along the given direction. The result is "lazy": it is only a view of the current matrix.

      The precise algorithm of thinning is not documented. Generally speaking, the "thinning" means removing elements from the boundary of any "object" (area of the matrix filled by 1). directionIndex specifies the "eroded side" of objects, or the direction of thinning:

      • 0 means removing elements from the left, i.e. from the side (x−1,y),
      • 1 means "diagonal" removal from the side (x−1,y−1),
      • 2 means removal from the side (x,y−1),
      • 3 means "diagonal" removal from the side (x+1,y−1),
      • 4 means removal from the right, i.e. from the side (x+1,y),
      • 5 means "diagonal" removal from the side (x+1,y+1),
      • 6 means removal from the side (x,y+1),
      • 7 means "diagonal" removal from the side (x−1,y+1).

      Though the algorithm is not documented, there are the following guarantees:

      • this algorithm never sets zero elements to unit: if the element of the current matrix with some coordinates (x0, y0) is 0, then the element with the same coordinates in the returned matrix is also 0;
      • each element of the returned matrix with coordinates (x0, y0) depends only on the elements in 3x3 aperture x0−1≤x≤x0+1, y0−1≤y≤y0+1 of the current matrix;
      • if all elements of the current matrix in 3x3 aperture x0−1≤x≤x0+1, y0−1≤y≤y0+1 are inside the matrix (i.e. 1≤x0≤dimX−2, 1≤y0≤dimY−2, dimX and dimY are dimensions of the matrix) and all they are equal to 1, then the element (x0, y0) in the returned matrix will be equal to 1.
      Specified by:
      asThinning in interface ThinningSkeleton
      Parameters:
      directionIndex - the direction of thinning, from 0 to 7.
      Returns:
      the thinned view if the current IterativeArrayProcessor.result() matrix.
      Throws:
      IllegalArgumentException - if directionIndex is not in 0..7 range.

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

    • performIteration

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

    • result

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

    • isThinningRequired

      public final boolean isThinningRequired(int directionIndex)
      Description copied from interface: ThinningSkeleton
      Returns true if and only if performIteration(ArrayContext) method really calls ThinningSkeleton.asThinning(int directionIndex) for this direction and copies its result to the result matrix. It depends on the implementation of this interface.
      Specified by:
      isThinningRequired in interface ThinningSkeleton
      Parameters:
      directionIndex - the direction of thinning, from 0 to 7.
      Returns:
      whether the matrix should be thinned along this direction.