Package net.algart.matrices.scanning

Class ConnectedObjectScanner

java.lang.Object
net.algart.matrices.scanning.ConnectedObjectScanner
All Implemented Interfaces:
Cloneable
public abstract class ConnectedObjectScanner extends Object implements Cloneable

Connected objects scanner: the class performing scanning and clearing connected objects, "drawn" on some n-dimensional updatable bit matrix.

More precisely, let's consider an AlgART bit matrix (Matrix<? extends UpdatableBitArray>). The connected object is a connected component of the graph, built on the matrix, where unit matrix elements are vertices, and neighbour unit elements are connected by edges. In 2D case, we can consider that the matrix contains images of some objects: unit bits (1) are white pixels, belonging to objects, zero bits (0) are black pixels of the background. Then our term "connected objects" describes the white objects, separated by black space.

We define two kinds of connectivity: straight and straight-and-diagonal. In the first case (straight connectivity), two unit elements with coordinates i0, i1, ..., in-1 and j0, j1, ..., jn-1 are neighbours if one from the coordinates differs by 1, but all other coordinates are equal:

∑ |ik−jk|=1

For 2D matrices, this connectivity kind is also known as "4-connectivity". It the second case (straight-and-diagonal connectivity), two unit elements are neighbours if several (at least one) from their coordinates differ by 1 and all other coordinates are equal:

max (|ik−jk|)=1

For 2D matrices, this connectivity kind is also known as "8-connectivity". The connectivity kind is described by ConnectivityType class.

The instance of this class works with some concrete bit matrix (Matrix<? extends UpdatableBitArray>), named the scanned matrix, and with some concrete connectivity type (ConnectivityType). Both the scanned matrix and the connectivity type are specified while creating the instance.

This class allows to visit all elements of the scanner matrix, belonging to one connected object, by its main clear method. "Visiting" means that this method calls ConnectedObjectScanner.ElementVisitor.visit(long[], long) method for every visited element, passing the index of the element in the underlying array of the matrix to that method, maybe, together with its coordinates in the matrix (if getting coordinates does not slow down the scanning algorithm).

Besides, the clear method clears (sets to 0) all visited elements in the bit matrix. But note: actual clearing may be not performed if forceClearing argument of this method is false.

There are following methods allowing to create the instance of this class:

You can switch to another scanned bit matrix with the same dimensions by matrix(Matrix) method.

You can use this instance (call its clear method) many times to scan different connected objects at one matrix. You may use nextUnitBit(long[]) method to find next connected object after scanning and clearing the previous one.

However, you must not use this instance after any modifications in the scanned matrix, performed by an external code. If you modify the matrix, you must create new instance of this class after this.

Note: this class works much faster (in several times) if the scanned matrix is created by SimpleMemoryModel. So, if the matrix is not created by SimpleMemoryModel and is not too large, we recommend to create its clone by SimpleMemoryModel and use this class for the clone.

Note: this class cannot process matrices with too large number of dimensions. The maximal allowed number of dimensions is Matrix.MAX_DIM_COUNT_FOR_SOME_ALGORITHMS, that is more than enough for most situations.

This class does not use multithreading optimization, unlike Arrays.copy(ArrayContext, UpdatableArray, Array) and similar methods. In other words, all methods of this class are executed in the current thread.

This class is not thread-safe, but is thread-compatible and can be synchronized manually, if multithread access is necessary. However, usually there are no reasons to use the same instance of this class in different threads: usually there is much better idea to create a separate instance for every thread.

Author:
Daniel Alievsky

  • Method Details

    • getBreadthFirstScanner

      public static ConnectedObjectScanner getBreadthFirstScanner(Matrix<? extends UpdatableBitArray> matrix, ConnectivityType connectivityType)
      Creates an instance of this class, implementing the classic breadth-first scanning algorithm.

      In this case, the clear method uses a queue, stored in an AlgART array, created via the memory model returned by the array context. While the queue is little enough, the algorithm stores it in a usual Java array instead of AlgART array.

      In typical situations, the queue stays very little (several kilobytes).

      It is a good choice for most situations. But getStacklessDepthFirstScanner(Matrix, ConnectivityType) method usually works faster for little matrices: see comments to that method.

      Parameters:
      matrix - the matrix that will be scanned and cleared by the created instance.
      connectivityType - the connectivity kind used by the created instance.
      Returns:
      new instance of this class.
      Throws:
      NullPointerException - if matrix or connectivityType argument is null.
      IllegalArgumentException - if matrix.dimCount() > Matrix.MAX_DIM_COUNT_FOR_SOME_ALGORITHMS.
      See Also:

    • getDepthFirstScanner

      public static ConnectedObjectScanner getDepthFirstScanner(Matrix<? extends UpdatableBitArray> matrix, ConnectivityType connectivityType)
      Creates an instance of this class, implementing the classic depth-first scanning algorithm.

      In this case, the clear method uses a stack, stored in an AlgART array, created via the memory model returned by the array context. While the stack is little enough, the algorithm stores it in a usual Java array instead of AlgART array.

      Unlike the breadth-first search, this algorithm often requires large stack. If the matrix contains large areas ("objects"), filled by 1, the length of stack is comparable with the number of unit elements in such areas, if the worst case (1-filled matrix) — the total number of matrix elements. Every stack element require several long values, so, the total occupied work memory can be in 100 and more times larger, than the memory occupied by the source bit matrix.

      The main advantage of this method is the well-specified order of visiting elements, defined by the depth-first search. It can be a good choice for scanning thin "skeletons", when the connectivity graph is a tree.

      Parameters:
      matrix - the matrix that will be scanned and cleared by the created instance.
      connectivityType - the connectivity kind used by the created instance.
      Returns:
      new instance of this class.
      Throws:
      NullPointerException - if matrix or connectivityType argument is null.
      IllegalArgumentException - if matrix.dimCount() > Matrix.MAX_DIM_COUNT_FOR_SOME_ALGORITHMS.
      See Also:

    • getStacklessDepthFirstScanner

      public static ConnectedObjectScanner getStacklessDepthFirstScanner(Matrix<? extends UpdatableBitArray> matrix, ConnectivityType connectivityType)
      Creates an instance of this class, implementing the classic depth-first scanning algorithm, but not using an explicit stack.

      In this case, the first call of clear method allocates a temporary work matrix with the same dimensions as the passed one. Then this matrix is used for saving information, necessary to perform correct depth-first search. The element type of the work matrix are byte, if connectivityType.numberOfNeighbours(matrix.dimCount())<128, or short in other cases (very exotic situation). If the total number of matrix elements (matrix.array().length()) is not greater than Arrays.SystemSettings.maxTempJavaMemory(), then the work matrix is allocated by SimpleMemoryModel. In other case, it is allocated by context.getMemoryModel() (context is the argument of clear method).

      This is the only algorithm, that always uses the constant amount of memory: in 8 times larger than the source bit matrix occupies (in 16 times for high number of dimensions). If the work matrix is allocated by SimpleMemoryModel, it is the quickest algorithm and the best choice in most situations. But if the matrix is large enough (Arrays.SystemSettings.maxTempJavaMemory() or more elements) and the context argument of clear method offers non-simple memory model, the breadth-first scanning algorithm is usually better choice.

      Please note: in this case the first call of clear method requires essential time for allocating and initializing work matrix. If you need to scan only one connected object, breadth-first scanning algorithm will probably be better choice.

      Parameters:
      matrix - the matrix that will be scanned and cleared by the created instance.
      connectivityType - the connectivity kind used by the created instance.
      Returns:
      new instance of this class.
      Throws:
      NullPointerException - if matrix or connectivityType argument is null.
      IllegalArgumentException - if matrix.dimCount() > Matrix.MAX_DIM_COUNT_FOR_SOME_ALGORITHMS.
      See Also:

    • getUncheckedBreadthFirstScanner

      public static ConnectedObjectScanner getUncheckedBreadthFirstScanner(Matrix<? extends UpdatableBitArray> matrix, ConnectivityType connectivityType)
      An analog of getBreadthFirstScanner(net.algart.arrays.Matrix<? extends net.algart.arrays.UpdatableBitArray>, net.algart.matrices.scanning.ConnectivityType) method, returning the instance, which works correctly only if all matrix elements with zero and maximal coordinates are zero.

      More precisely, this method may be used only if one of the following conditions is complied:

      1. each matrix bit with coordinates i0,i1,...,in−1, where at least one ij=0 or ij=matrix.dim(j)-1, is zero;
      2. or each matrix bit with coordinates i0,i1,...,in−1, where at least one ij=matrix.dim(j)-1, is zero, and also each matrix bit with last coordinate in−1=0 or in−1=1 is zero (first two lines in the 2-dimensional case).

      Here n=matrix.dimCount() is the number of matrix dimensions. If both conditions are not complied, the clear method of the returned instance can visit (and clear) some extra elements or can throw unexpected IndexOutOfBoundsException while scanning. (And it is the only undesirable effect; no other data will be damaged, no invariants will be violated.)

      The scanner, returned by this method, works faster than the scanner, returned by getBreadthFirstScanner(Matrix, ConnectivityType). So, if possible, we recommend to provide the required condition and to use this method. The simplest way to provide the necessary 1st condition is the following call: 

       matrix.subMatrix(from, to, Matrix.ContinuationMode.ZERO_CONSTANT);

      where all from[k]==-1 and to[k]=matrix.dim(k)+1. Note: please copy the matrix, created by this subMatrix call, to some newly created bit matrix, in other case the performance will not be improved (because access to each element of the submatrix is slow).

      Parameters:
      matrix - the matrix that will be scanned and cleared by the created instance.
      connectivityType - the connectivity kind used by the created instance.
      Returns:
      new instance of this class.
      Throws:
      NullPointerException - if matrix or connectivityType argument is null.
      IllegalArgumentException - if matrix.dimCount() > Matrix.MAX_DIM_COUNT_FOR_SOME_ALGORITHMS.

    • getUncheckedDepthFirstScanner

      public static ConnectedObjectScanner getUncheckedDepthFirstScanner(Matrix<? extends UpdatableBitArray> matrix, ConnectivityType connectivityType)
      An analog of getDepthFirstScanner(net.algart.arrays.Matrix<? extends net.algart.arrays.UpdatableBitArray>, net.algart.matrices.scanning.ConnectivityType) method, returning the instance, which works correctly only if all matrix elements with zero and maximal coordinates are zero.

      More precisely, this method may be used only if one of the following conditions is complied:

      1. each matrix bit with coordinates i0,i1,...,in−1, where at least one ij=0 or ij=matrix.dim(j)-1, is zero;
      2. or each matrix bit with coordinates i0,i1,...,in−1, where at least one ij=matrix.dim(j)-1, is zero, and also each matrix bit with last coordinate in−1=0 or in−1=1 is zero (first two lines in the 2-dimensional case).

      Here n=matrix.dimCount() is the number of matrix dimensions. If both conditions are not complied, the clear method of the returned instance can visit (and clear) some extra elements or can throw unexpected IndexOutOfBoundsException while scanning. (And it is the only undesirable effect; no other data will be damaged, no invariants will be violated.)

      The scanner, returned by this method, works faster than the scanner, returned by getDepthFirstScanner(Matrix, ConnectivityType). So, if possible, we recommend to provide the required condition and to use this method. The simplest way to provide the necessary 1st condition is the following call: 

       matrix.subMatrix(from, to, Matrix.ContinuationMode.ZERO_CONSTANT);

      where all from[k]==-1 and to[k]=matrix.dim(k)+1. Note: please copy the matrix, created by this subMatrix call, to some newly created bit matrix, in other case the performance will not be improved (because access to each element of the submatrix is slow).

      Parameters:
      matrix - the matrix that will be scanned and cleared by the created instance.
      connectivityType - the connectivity kind used by the created instance.
      Returns:
      new instance of this class.
      Throws:
      NullPointerException - if matrix or connectivityType argument is null.
      IllegalArgumentException - if matrix.dimCount() > Matrix.MAX_DIM_COUNT_FOR_SOME_ALGORITHMS.

    • getUncheckedStacklessDepthFirstScanner

      public static ConnectedObjectScanner getUncheckedStacklessDepthFirstScanner(Matrix<? extends UpdatableBitArray> matrix, ConnectivityType connectivityType)
      An analog of getStacklessDepthFirstScanner(net.algart.arrays.Matrix<? extends net.algart.arrays.UpdatableBitArray>, net.algart.matrices.scanning.ConnectivityType) method, returning the instance, which works correctly only if all matrix elements with zero and maximal coordinates are zero.

      More precisely, this method may be used only if one of the following conditions is complied:

      1. each matrix bit with coordinates i0,i1,...,in−1, where at least one ij=0 or ij=matrix.dim(j)-1, is zero;
      2. or each matrix bit with coordinates i0,i1,...,in−1, where at least one ij=matrix.dim(j)-1, is zero, and also each matrix bit with last coordinate in−1=0 or in−1=1 is zero (first two lines in the 2-dimensional case).

      Here n=matrix.dimCount() is the number of matrix dimensions. If both conditions are not complied, the clear method of the returned instance can visit (and clear) some extra elements or can throw unexpected IndexOutOfBoundsException while scanning. (And it is the only undesirable effect; no other data will be damaged, no invariants will be violated.)

      The scanner, returned by this method, works faster than the scanner, returned by getStacklessDepthFirstScanner(Matrix, ConnectivityType). So, if possible, we recommend to provide the required condition and to use this method. The simplest way to provide the necessary 1st condition is the following call: 

       matrix.subMatrix(from, to, Matrix.ContinuationMode.ZERO_CONSTANT);

      where all from[k]==-1 and to[k]=matrix.dim(k)+1. Note: please copy the matrix, created by this subMatrix call, to some newly created bit matrix, in other case the performance will not be improved (because access to each element of the submatrix is slow).

      Parameters:
      matrix - the matrix that will be scanned and cleared by the created instance.
      connectivityType - the connectivity kind used by the created instance.
      Returns:
      new instance of this class.
      Throws:
      NullPointerException - if matrix or connectivityType argument is null.
      IllegalArgumentException - if matrix.dimCount() > Matrix.MAX_DIM_COUNT_FOR_SOME_ALGORITHMS.

    • clone

      public abstract ConnectedObjectScanner clone()
      Creates the instance, implementing the same algorithm with the same connectivity kind an the same scanned matrix as this one. The new instance has the same maxUsedMemory() value as this one. If this instance allocated some temporary buffers, they are not inherited: the returned instance will allocate and use its own temporary buffers.
      Overrides:
      clone in class Object

    • reset

      public final void reset()
      Resets all internal buffers before scanning new matrix. Equivalent to the call matrix(matrix()).

    • matrix

      public void matrix(Matrix<? extends UpdatableBitArray> matrix)
      Changes the current scanned bit matrix for this instance. New matrix must have the same dimensions as the current one.

      Note: you must call this method before starting processing the matrix, even if it is actually the same matrix. This call not only sets the reference to matrix, but also clears work buffers, where the algorithm stores necessary information for correct depth-first search. Without this, a scanner can use the invalid information and work incorrectly.

      If the actual reference matrix, passed to this method, did not change, you can use instead reset() method.

      Parameters:
      matrix - new matrix that will be scanned and cleared by this instance.
      Throws:
      NullPointerException - if the argument is null.
      SizeMismatchException - if the dimensions of the passed matrix differ from the dimensions of the current one.
      See Also:

    • matrix

      public Matrix<? extends UpdatableBitArray> matrix()
      Returns a reference to the matrix, scanned by this object. It is specified while creating this instance or as an argument of matrix(Matrix) method.
      Returns:
      a reference to the matrix, scanned by this object.

    • connectivityType

      public ConnectivityType connectivityType()
      Returns the connectivity kind, used by this object. It is specified while creating this instance.
      Returns:
      the connectivity kind, used by this object.

    • nextUnitBit

      public boolean nextUnitBit(long[] coordinates)
      Finds the next unit matrix element, starting from coordinates, saves the result in the same coordinates array and returns true if such element was found. If the element with specified coordinates is already unit, returns true and does not change coordinates array. If the unit element was not found, returns false and does not change coordinates array.

      If clear(net.algart.arrays.ArrayContext, net.algart.matrices.scanning.ConnectedObjectScanner.ElementVisitor, long[], boolean) method was never called with forceClearing=false, this method is equivalent to the following operators: 

       long from = matrix.index(coordinates);
 long index = matrix().array().indexOf(from, matrix().size(), true);
 if (index == -1) {
     return false;
 } else {
     matrix.coordinates(index, coordinates);
     return true;
 }
      Parameters:
      coordinates - coordinates of some matrix element; the coordinates of the next unit element will be saved here.
      Returns:
      true if the next unit element was found.
      Throws:
      NullPointerException - if coordinate argument is null.
      IllegalArgumentException - if coordinate.length is not equal to matrix().dimCount().
      IndexOutOfBoundsException - if some coordinates are out of the scanned matrix.

    • clear

      public long clear(ArrayContext context, ConnectedObjectScanner.ElementVisitor elementVisitor, long[] coordinates, boolean forceClearing)
      Visits all unit (1) elements of the matrix, belonging to the connected object containing the element with the specified coordinates, calls elementVisitor.visit method for each element and clears this element (UpdatableBitArray.clearBit(long)). Returns the number of visited elements. If the element with the specified coordinates is zero, does nothing and returns 0.

      However, if forceClearing argument is false, this method may skip actual clearing the visited elements in the scanned matrix, but clear bits in some internal buffer instead. In this case, the nextUnitBit(long[]) method will work as if the bits was actually cleared. This mode is useful if you don't really need to clear bits in the source matrix, but only need to visit all unit elements: this mode can improve performance. If forceClearing argument is true, the behavior is strict: all visited elements will be immediately cleared in the scanned matrix.

      The elementVisitor.visit method is called before clearing the element.

      The elementVisitor argument may be null: then this method only clears the elements of the connected object. It may be enough if your only intention is to count the elements of the connected object.

      The order of visiting elements is not specified and depends on concrete implementation of this class.

      This method never modifies the passed coordinates array: it is cloned in the beginning of the method and is not used after this. It can be important in a case of multithread access.

      Parameters:
      context - the context of scanning; may be null, then will be ignored. The main purpose of the context in most implementation is to allow interruption of this method via ArrayContext.checkInterruption() and to allocate work memory via ArrayContext.getMemoryModel(). This method does not try to update execution progress via the context: its methods ArrayContext.updateProgress(net.algart.arrays.ArrayContext.Event) and ArrayContext.checkInterruptionAndUpdateProgress(java.lang.Class<?>, long, long) are not called.
      elementVisitor - the visitor, called for every visited element; may be null, then will be ignored.
      coordinates - the coordinates of some matrix element, belonging to the connected object that should be scanned.
      forceClearing - false value allows the method not to perform actual clearing bits in the scanned matrix; true value requires actual clearing.
      Returns:
      the number of matrix elements in the connected object or 0 if the bit with specified coordinates is zero.
      Throws:
      NullPointerException - if coordinates argument is null.
      IllegalArgumentException - if the number of passed coordinates (coordinates.length) is not equal to the number of dimensions of the scanned matrix.
      IndexOutOfBoundsException - if some coordinates are out of the scanned matrix.
      OutOfMemoryError - (low probability) if the form of the object is too complex and there is not enough memory to allocate necessary data structures.

    • clear

      public long clear(ArrayContext context, ConnectedObjectScanner.ElementVisitor elementVisitor, long... coordinates)
      Equivalent to clear(context, elementVisitor, coordinates, true).
      Parameters:
      context - the context of scanning; may be null, then will be ignored. The main purpose of the context in most implementation is to allow interruption of this method via ArrayContext.checkInterruption() and to allocate work memory via ArrayContext.getMemoryModel().
      elementVisitor - the visitor, called for every visited element; may be null, then will be ignored.
      coordinates - the coordinates of some matrix element, belonging to the connected object that should be scanned.
      Returns:
      the number of matrix elements in the connected object or 0 if the bit with specified coordinates is zero.
      Throws:
      NullPointerException - if coordinates argument is null.
      IllegalArgumentException - if the number of passed coordinates (coordinates.length) is not equal to the number of dimensions of the scanned matrix.
      IndexOutOfBoundsException - if some coordinates are out of the scanned matrix.
      OutOfMemoryError - (low probability) if the form of the object is too complex and there is not enough memory to allocate necessary data structures.

    • clear

      public long clear(ArrayContext context, long[] coordinates, boolean forceClearing)
      Equivalent to clear(context, null, coordinates, forceClearing).
      Parameters:
      context - the context of scanning; may be null, then will be ignored. The main purpose of the context in most implementation is to allow interruption of this method via ArrayContext.checkInterruption() and to allocate work memory via ArrayContext.getMemoryModel().
      coordinates - the coordinates of some matrix element, belonging to the connected object that should be scanned.
      forceClearing - false value allows the method not to perform actual clearing bits in the scanned matrix; true value requires actual clearing.
      Returns:
      the number of matrix elements in the connected object or 0 if the bit with specified coordinates is zero.
      Throws:
      NullPointerException - if coordinates argument is null.
      IllegalArgumentException - if the number of passed coordinates (coordinates.length) is not equal to the number of dimensions of the scanned matrix.
      IndexOutOfBoundsException - if some coordinates are out of the scanned matrix.

    • clear

      public long clear(ArrayContext context, long... coordinates)
      Equivalent to clear(context, null, coordinates, true).
      Parameters:
      context - the context of scanning; may be null, then will be ignored. The main purpose of the context in most implementation is to allow interruption of this method via ArrayContext.checkInterruption() and to allocate work memory via ArrayContext.getMemoryModel().
      coordinates - the coordinates of some matrix element, belonging to the connected object that should be scanned.
      Returns:
      the number of matrix elements in the connected object or 0 if the bit with specified coordinates is zero.
      Throws:
      NullPointerException - if coordinates argument is null.
      IllegalArgumentException - if the number of passed coordinates (coordinates.length) is not equal to the number of dimensions of the scanned matrix.
      IndexOutOfBoundsException - if some coordinates are out of the scanned matrix.
      OutOfMemoryError - (low probability) if the form of the object is too complex and there is not enough memory to allocate necessary data structures.

    • clearAllBySizes

      public long clearAllBySizes(ArrayContext context, Matrix<? extends BitArray> mask, long minNonClearedSize, long maxNonClearedSize)
      Clears all elements of all connected objects in the matrix, the volume of which is less than minNonClearedSize or greater than maxNonClearedSize. The volume here is:
      • just the number of elements in a connected object (result of clear method) — if the mask argument is null;
      • the number of such elements in a connected object, for which the corresponding element in the mask bit matrix (with the same coordinates) is 1 — if the mask argument is not null.

      If mask matrix is not null, it must have the same dimensions as the scanned matrix.

      This method creates a temporary copy of the scanned matrix and performs a loop of nextUnitBit(long[]) and clear methods. The temporary matrix is allocated while the first call of this method and used again in the further calls.

      This method also creates a clone of this scanner. It leads to additional memory usage in a case of stack-less scanners, created by getStacklessDepthFirstScanner(net.algart.arrays.Matrix<? extends net.algart.arrays.UpdatableBitArray>, net.algart.matrices.scanning.ConnectivityType) and getUncheckedStacklessDepthFirstScanner(net.algart.arrays.Matrix<? extends net.algart.arrays.UpdatableBitArray>, net.algart.matrices.scanning.ConnectivityType) methods.

      Note: this method calls reset() in the very beginning.

      Parameters:
      context - the context of scanning; may be null, then will be ignored.
      mask - the bit mask, on which the volume should be counted; may be null, then the volume is the full number of elements in connected objects.
      minNonClearedSize - minimal volume of connected objects that will not be cleared.
      maxNonClearedSize - maximal volume of connected objects that will not be cleared.
      Returns:
      the total number of cleared elements.
      Throws:
      SizeMismatchException - if mask!=null, and mask and the scanned matrix have different dimensions.

    • clearAllConnected

      public long clearAllConnected(ArrayContext context, Matrix<? extends UpdatableBitArray> objects)
      Clears all elements of all connected objects in the matrix, corresponding to this object, and also clears all objects in the passed second matrix with same sizes, which are connected with at least one unit (1) element of the first matrix. In other words, this method just calls clear method for coordinates, corresponding to all unit elements of the first matrix, in a clone of this scanner, where the processed matrix is replaced with objects.

      This method creates a clone of this scanner. It leads to additional memory usage in a case of stack-less scanners, created by getStacklessDepthFirstScanner(net.algart.arrays.Matrix<? extends net.algart.arrays.UpdatableBitArray>, net.algart.matrices.scanning.ConnectivityType) and getUncheckedStacklessDepthFirstScanner(net.algart.arrays.Matrix<? extends net.algart.arrays.UpdatableBitArray>, net.algart.matrices.scanning.ConnectivityType) methods. So, we do not recommend using this method for such scanners, if you want to call it many times for the same intance of this class.

      Note: this method calls reset() in the very beginning.

      Parameters:
      context - the context of scanning; may be null, then will be ignored.
      objects - the second matrix, where this method clears all objects connected with some objects in the matrix, corresponding to this object.
      Returns:
      the total number of cleared elements in objects.
      Throws:
      NullPointerException - if objects argument is null.
      SizeMismatchException - if objects and the scanned matrix have different dimensions.

    • updateProgress

      public final void updateProgress(ArrayContext context, long... coordinates)
      Calls context.updateProgress with an event, created by the following operator: new ArrayContext.Event(boolean.class, matrix().size(), matrix().index(coordinates)). Does nothing if context==null.

      The method can be useful while sequentially scanning the matrix via a loop of clear and nextUnitBit calls.

      Parameters:
      context - the context of execution; may be null, then it will be ignored.
      coordinates - coordinates of currently scanned matrix element.

    • maxUsedMemory

      public long maxUsedMemory()
      Returns the maximal amount of work memory (in bytes), that was allocated by this instance allocated during its work since its creation or calling resetUsedMemory() method. Can be used for profiling or debugging needs.
      Returns:
      the maximal amount of work memory (in bytes), used by this instance.

    • resetUsedMemory

      public void resetUsedMemory()
      Resets the memory counter returned by maxUsedMemory() method.

    • freeResources

      public void freeResources(ArrayContext context)
      If there are some AlgART arrays or matrices, allocated by this object for storing temporary data, this method calls Array.freeResources(context) / Matrix.freeResources(context) methods for them.

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

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