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 {@link #nextUnitBit} 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. {@link ConnectedObjectScanner.ElementVisitor#visit 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.
@param 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 {@link ArrayContext#checkInterruption()} and to allocatework memory via {@link ArrayContext#getMemoryModel()}. This method does not try to update execution progress via the context: its methods {@link ArrayContext#updateProgress} and{@link ArrayContext#checkInterruptionAndUpdateProgress} are not called. @param elementVisitor the visitor, called for every visited element;may be null, then will be ignored. @param coordinates the coordinates of some matrix element, belonging to the connected objectthat should be scanned. @param forceClearing false value allows the method not to perform actual clearingbits in the scanned matrix; true value requires actual clearing. @return the number of matrix elements in the connected objector 0 if the bit with specified coordinates is zero. @throws NullPointerException if coordinates argument is null. @throws IllegalArgumentException if the number of passed coordinates (coordinates.length)is not equal to the number of dimensions of the {@link #matrix() scanned matrix}. @throws IndexOutOfBoundsException if some coordinates are out of the {@link #matrix() scanned matrix}. @throws OutOfMemoryError (low probability) if the form of the object is too complex and there isnot enough memory to allocate necessary data structures. | |