Class TiledConvolution

java.lang.Object
net.algart.matrices.linearfiltering.TiledConvolution
All Implemented Interfaces:
ArrayProcessor, ArrayProcessorWithContextSwitching, Convolution

public class TiledConvolution extends Object implements Convolution

The filter allowing to transform any Convolution object to another instance of that interface, which uses some given tiler for processing the source matrix (an argument of Convolution methods).

This object is built on the base of some parent object, implementing Convolution, and some tiler (an instance of TiledApertureProcessorFactory class). This object works almost identically to the parent object with the only difference, that it uses the specified tiler for performing all operations.

More precisely, each method of this object creates an implementation p of ApertureProcessor interface. The only thing, performed by process method of that object p, is calling the same method of parent object with the arguments of p.process(dest,src) method (the source matrix is retrieved from src, the result is saved into dest). The dependence aperture p.dependenceAperture(...) is calculated automatically on the base of the patterns and the performed operation. Then, the method of this object executes the required operation with help of tiler().tile(p).process(dest,src) call — the source matrix is passed via src, the result is retrieved from dest. As a result, the same operation is performed tile-by-tile.

The method asConvolution(Matrix, WeightedPattern) is an exception from this rule. These methods of this class works in the same way, as in ContinuedConvolution class, the continuation mode of which is equal to tiler().continuationMode().

Note: in improbable cases, when the dimensions of the source matrix and/or the sizes of the pattern are extremely large (about 263), so that the necessary appended matrices should have dimensions or total number of elements, greater than Long.MAX_VALUE, the methods of this class throw IndexOutOfBoundsException and do nothing. See comments to TiledApertureProcessorFactory class, "Restriction" section for precise details. Of course, these are very improbable cases.

This class is immutable and thread-safe: there are no ways to modify settings of the created instance.

Author:
Daniel Alievsky
  • Method Details

    • getInstance

      public static TiledConvolution getInstance(Convolution parent, TiledApertureProcessorFactory tiler)
      Returns new instance of this class with the passed parent Convolution object and the specified processing tiler.

      Note: the context of the created object is retrieved from parent.context(), and the context of the passed tiler is automatically replaced with the same one — the current tiler of the created object is tiler.context(newInstance.context()). It means that the context of the passed tiler is not important and can be null.

      Parameters:
      parent - parent object: the instance of Convolution interface that will perform all operations.
      tiler - the tiler, which will be used for processing matrices by this class.
      Returns:
      new instance of this class.
      Throws:
      NullPointerException - if parent or tiler argument is null.
    • parent

      public Convolution parent()
      Returns the parent Convolution object, passed to getInstance(Convolution, TiledApertureProcessorFactory) method.
      Returns:
      the parent Convolution object.
    • tiler

      Returns the processing tiler that will be used for tiled processing the source matrices.
      Returns:
      the tiler, which is used for tiled processing the source matrices.
      See Also:
    • context

      public ArrayContext context()
      Description copied from interface: ArrayProcessor
      Returns the current context used by this instance for all operations. This method may return null; the classes, implementing this interface, should work in this situation as while using ArrayContext.DEFAULT context.
      Specified by:
      context in interface ArrayProcessor
      Returns:
      the current context used by this instance; may be null.
    • context

      public Convolution context(ArrayContext newContext)
      Switches the context: returns an instance, identical to this one excepting that it uses the specified newContext for all operations. Usually, the returned instance is used only for performing a subtask of the full task.

      More precisely, this method is equivalent to getInstance(parent().context(newContext), tiler()).

      Specified by:
      context in interface ArrayProcessorWithContextSwitching
      Specified by:
      context in interface Convolution
      Parameters:
      newContext - another context, used by the returned instance; may be null.
      Returns:
      new instance with another context.
    • isPseudoCyclic

      public boolean isPseudoCyclic()
      Returns true, if this class works in the default pseudo-cyclic continuation mode. More precisely, returns true if and only if tiler().continuationMode() is PSEUDO_CYCLIC.
      Specified by:
      isPseudoCyclic in interface Convolution
      Returns:
      whether this class works in the pseudo-cyclic continuation mode.
    • increment

      public double increment(Class<?> elementType)
      Specified by:
      increment in interface Convolution
    • asConvolution

      public Matrix<? extends PArray> asConvolution(Matrix<? extends PArray> src, WeightedPattern pattern)
      Description copied from interface: Convolution
      Equivalent to asConvolution(src.type(PArray.class), src, pattern). In other words, the element type of the returned matrix is chosen the same as in src matrix.
      Specified by:
      asConvolution in interface Convolution
      Parameters:
      src - the source matrix.
      pattern - the pattern.
      Returns:
      the "lazy" matrix containing the convolution of the source matrix with the given pattern.
    • asConvolution

      public <T extends PArray> Matrix<T> asConvolution(Class<? extends T> requiredType, Matrix<? extends PArray> src, WeightedPattern pattern)
      Description copied from interface: Convolution
      Returns an immutable view of the passed source matrix, such that any reading data from it calculates and returns the convolution of the source matrix by the specified pattern. See Convolution.convolution(Class, Matrix, WeightedPattern) method about the "convolution" term.

      The matrix, returned by this method, is immutable, and the class of its built-in array implements one of the basic interfaces BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray, FloatArray or DoubleArray. The class of desired interface (one of 8 possible classes) must be passed as requiredType argument. So, it defines the element type of the returned matrix. For example, if requiredType=ByteArray.class, the returned matrix consists of byte elements. The rules of casting the real numbers, results of the convolution, to the desired element type are the same as in Arrays.asFuncArray(boolean, net.algart.math.functions.Func, Class, PArray...) method with the argument truncateOverflows=true.

      The result is usually "lazy", that means that this method finishes immediately and all actual calculations are performed while getting elements of the returned matrix. It is true for all implementations provided by this package. However, some implementations may not support lazy dilation; then this method will be equivalent to Convolution.convolution(Class, Matrix, WeightedPattern).

      Please note: this method does not require time, but the resulting matrix can work slowly! for example, reading all its content than work much slower than Convolution.convolution(Class, Matrix, WeightedPattern) method for some complex patterns. Usually you should use it only for very little patterns, or if you know that the implementation of this interface does not provide better algorithm for non-"lazy" Convolution.convolution(Class, Matrix, WeightedPattern) method.

      Specified by:
      asConvolution in interface Convolution
      Parameters:
      requiredType - desired type of the built-in array in the returned matrix.
      src - the source matrix.
      pattern - the pattern.
      Returns:
      the "lazy" matrix containing the convolution of the source matrix with the given pattern.
    • convolution

      public Matrix<? extends UpdatablePArray> convolution(Matrix<? extends PArray> src, WeightedPattern pattern)
      Description copied from interface: Convolution
      Returns a new updatable matrix, containing the convolution of the source matrix by the specified pattern.

      Usually convolution means the weighted sum of the set of matrices, obtained by pseudo-cyclic shifting the source matrix by the vectors, equal to all pattern points, with weights, equal to weights of the pattern points. More precisely, let mi=Matrices.asShifted(src,ip.coordinates()), where ip is the point #i from all points contained in the pattern, and let wi=pattern.weight(ip). Then the every element of the returned matrix is the weighted sum of all corresponding elements of all mi matrices:

      wimi
      The element type of the created matrix is the same as the element type of the source one. The byte and short elements are considered to be unsigned. If the element type if integer, the precise is rounded to the nearest integer.

      The BasicConvolution class strictly complies this definition. However, other implementations of this interface may use alternate definitions of the convolution term. For example, elements outside the matrix may be supposed to be filled according some non-trivial rules instead of pseudo-cyclic continuation (as in ContinuedConvolution objects), or only some region of the matrix may be processed, etc.

      Specified by:
      convolution in interface Convolution
      Parameters:
      src - the source matrix.
      pattern - the pattern.
      Returns:
      the result of convolution of the source matrix with the given pattern.
      See Also:
    • convolution

      public <T extends PArray> Matrix<? extends T> convolution(Class<? extends T> requiredType, Matrix<? extends PArray> src, WeightedPattern pattern)
      Specified by:
      convolution in interface Convolution
    • convolution

      public void convolution(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, WeightedPattern pattern)
      Specified by:
      convolution in interface Convolution