Interface Convolution

All Superinterfaces:
ArrayProcessor, ArrayProcessorWithContextSwitching
All Known Implementing Classes:
AbstractConvolution, BasicConvolution, ContinuedConvolution, TiledConvolution

public interface Convolution extends ArrayProcessorWithContextSwitching
  • Method Details

    • context

      Convolution context(ArrayContext newContext)
      Description copied from interface: ArrayProcessorWithContextSwitching
      Switches the context: returns an instance, identical to this one excepting that it uses the specified newContext for all operations. The returned instance is usually a clone of this one, but there is no guarantees that it is a deep clone. Usually, the returned instance is used only for performing a subtask of the full task.
      Specified by:
      context in interface ArrayProcessorWithContextSwitching
      Parameters:
      newContext - another context, used by the returned instance; may be null.
      Returns:
      new instance with another context.
    • isPseudoCyclic

      boolean isPseudoCyclic()
      Returns true, if this class works in the default pseudo-cyclic continuation mode.

      More precisely, it means that when the value in some element of the processed matrix, returned by a method of this class, depends on elements of the source matrix, lying outside its bounds, then it is supposed that the values outside the source matrix are calculated as described in Matrix.ContinuationMode.PSEUDO_CYCLIC. Exactly such behaviour is specified in the comments to the convolution(Matrix, WeightedPattern) method as the default definition of convolution.

      This method returns true in BasicConvolution implementation. However, it usually returns false in ContinuedConvolution class — excepting the only degenerated case when the used continuation mode is PSEUDO_CYCLIC.

      Returns:
      whether this class works in the pseudo-cyclic continuation mode.
    • increment

      double increment(Class<?> elementType)
    • asConvolution

      Matrix<? extends PArray> asConvolution(Matrix<? extends PArray> src, WeightedPattern pattern)
      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.
      Parameters:
      src - the source matrix.
      pattern - the pattern.
      Returns:
      the "lazy" matrix containing the convolution of the source matrix with the given pattern.
      Throws:
      NullPointerException - if one of the arguments is null.
    • asConvolution

      <T extends PArray> Matrix<T> asConvolution(Class<? extends T> requiredType, Matrix<? extends PArray> src, WeightedPattern pattern)
      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(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(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(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(Class, Matrix, WeightedPattern) method.

      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.
      Throws:
      NullPointerException - if one of the arguments is null.
    • convolution

      Matrix<? extends UpdatablePArray> convolution(Matrix<? extends PArray> src, WeightedPattern pattern)
      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.

      Parameters:
      src - the source matrix.
      pattern - the pattern.
      Returns:
      the result of convolution of the source matrix with the given pattern.
      Throws:
      NullPointerException - if one of the arguments is null.
      See Also:
    • convolution

      <T extends PArray> Matrix<? extends T> convolution(Class<? extends T> requiredType, Matrix<? extends PArray> src, WeightedPattern pattern)
    • convolution

      void convolution(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, WeightedPattern pattern)