Package net.algart.matrices

Class ContinuedStreamingApertureProcessor

java.lang.Object
net.algart.arrays.AbstractArrayProcessorWithContextSwitching
net.algart.matrices.StreamingApertureProcessor
net.algart.matrices.ContinuedStreamingApertureProcessor
All Implemented Interfaces:
Cloneable, ArrayProcessor, ArrayProcessorWithContextSwitching
public class ContinuedStreamingApertureProcessor extends StreamingApertureProcessor

The filter allowing to transform any streaming aperture procesor to another instance of that class, which uses some non-trivial form of continuation outside the source matrix.

This object is built on the base of some parent object, extending StreamingApertureProcessor, and some continuation mode. This object works almost identically to the parent object with the only exception, that it uses the specified continuation model instead of the default pseudo-cyclic continuation, described in comments to StreamingApertureProcessor.

More precisely, both asProcessed(Class, Matrix, List, Pattern) and process(Matrix, Matrix, List, Pattern) methods of this object call the corresponding methods of the parent one. But before calling them, the source matrix M is appended (outside its bounds) by some area of additional values with help of Matrix.subMatrix(long[], long[], net.algart.arrays.Matrix.ContinuationMode) method, using the continuation mode of this filter, and all additional matrices M0, M1, ..., MK−1 are analogously appended until the same sizes with zeros (Matrix.ContinuationMode.ZERO_CONSTANT). So, all dimensions of the appended matrices are little greater than the corresponding dimensions of the source ones, and extra elements are (virtually) filled according the given continuation mode (the source matrix M) or by zeros (additional matrices Mi). The size of extension along all coordinates depends on the pattern (aperture shape). After this, the corresponding method of parent object processes the appended matrix. In a case of asProcessed method, the corresponding submatrix of the result is extracted, with dimensions, equal to the dimensions of the source matrix (by using Matrix.subMatrix(long[], long[]) method), and the method returns this submatrix. In a case of process method, the destination (updatable) R matrix is (virtually) extended like the source M matrix before calculations with help of Matrix.subMatrix(long[], long[], net.algart.arrays.Matrix.ContinuationMode) method; so, the calculated data are correctly stored into the original R matrix.

The appending along all coordinates is performed in such a way, that the resulting matrix is the same, as if the source matrix would be virtually appended until the infinity along all directions, according the selected continuation mode.

Note: we append the additional matrices Mk with 0.0 constant instead of using the selected continuation mode. It is possible (as well as appending with any other values) because the element of the resulting matrix R at every position x, according the basic specification of StreamingApertureProcessor class, should depend only on the elements w0, w1, ..., wK−1 of the additional matrices Mk, placed at the same position x.

Note: Matrix.ContinuationMode.NONE continuation mode cannot be used in this class: such value of continuationMode argument of the instantiation method getInstance(StreamingApertureProcessor, Matrix.ContinuationMode) leads to IllegalArgumentException.

Note: in an improbable case, 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. Of course, if is very improbable case.

This class is an example of non-standard implementation of streaming aperture processor, which does not comply with the strict definition from the comments to StreamingApertureProcessor class. (But this implementation is still standard, if continuationMode() is PSEUDO_CYCLIC and the parent processor is standard.)

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 ContinuedStreamingApertureProcessor getInstance(StreamingApertureProcessor parent, Matrix.ContinuationMode continuationMode)
      Returns new instance of this class with the passed parent StreamingApertureProcessor object and the specified continuation mode. See comments to Matrix.ContinuationMode class for more information about possible continuations.
      Parameters:
      parent - the instance of StreamingApertureProcessor class that will perform all operations.
      continuationMode - the mode of continuation outside the source matrix.
      Returns:
      new instance of this class.
      Throws:
      NullPointerException - if parent or continuationMode argument is null.
      IllegalArgumentException - if continuationMode==Matrix.ContinuationMode.NONE.
      See Also:

    • parent

      public StreamingApertureProcessor parent()
      Returns the parent StreamingApertureProcessor object, passed to getInstance(StreamingApertureProcessor, Matrix.ContinuationMode) method.
      Returns:
      the parent StreamingApertureProcessor object.

    • continuationMode

      public Matrix.ContinuationMode continuationMode()
      Returns the continuation mode, used by this object for virtual continuing the source matrix. The returned mode is equal to the corresponding argument of getInstance(StreamingApertureProcessor, Matrix.ContinuationMode) method.
      Returns:
      the continuation mode, that will be used for continuation outside the source matrix.

    • context

      public StreamingApertureProcessor 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.
      Specified by:
      context in interface ArrayProcessorWithContextSwitching
      Overrides:
      context in class StreamingApertureProcessor
      Parameters:
      newContext - another context, used by the returned instance; may be null.
      Returns:
      new instance with another context.

    • isStandardImplementation

      public boolean isStandardImplementation()
      Description copied from class: StreamingApertureProcessor
      Returns true if there is a guarantee that this object is a standard implementations of this class. For non-standard implementation, this method usually returns false. See comments to StreamingApertureProcessor class for more details.
      Overrides:
      isStandardImplementation in class StreamingApertureProcessor
      Returns:
      whether this implementation is standard.

    • asProcessed

      public <T extends PArray> Matrix<T> asProcessed(Class<? extends T> requiredType, Matrix<? extends PArray> src, List<? extends Matrix<? extends PArray>> additionalMatrices, Pattern pattern)
      Description copied from class: StreamingApertureProcessor
      Returns an immutable view of the passed source matrix M=src and the passed additional matrices Mk=additionalMatrices.get(k), such that any reading data from it calculates and returns the result R of this streaming aperture processor. See the comments to this class for more details.

      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. The rules of casting the floating-point result of the processing function g to the desired element type depend on implementation. In many (but not all) implementations they are the same as in Arrays.asFuncArray(boolean, net.algart.math.functions.Func, Class, PArray...) method with the argument truncateOverflows=true.

      The concrete algorithm, implementing by this class, can require some number of additional arguments Mk. If the number of matrices in the passed list additionalMatrices is less than the required one, this method throws IllegalArgumentException. If the number of passed matrices is greater than the required one, it is not an error: the extra arguments are ignored.

      Usually you should use process method, which work faster than this method.

      Specified by:
      asProcessed in class StreamingApertureProcessor
      Parameters:
      requiredType - the desired type of the built-in array in the returned matrix.
      src - the source matrix M.
      additionalMatrices - the additional matrices M0, M1, ..., MK−1.
      pattern - the aperture shape P.
      Returns:
      the "lazy" matrix containing the result of this algorithm.

    • process

      public void process(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, List<? extends Matrix<? extends PArray>> additionalMatrices, Pattern pattern)
      Description copied from class: StreamingApertureProcessor
      Processes the passed source matrix M=src and the passed additional matrices Mk=additionalMatrices.get(k) by this streaming aperture processor and stores the result R in dest argument. See the comments to this class for more details.

      This default implementations is based on one or more calls of asProcessed method and copying its result into dest matrix. The requiredType argument of asProcessed method is chosen as dest.type(PArray.class). If you need to create a non-standard implementation (a class which does not represent a streaming aperture processor, complying with strict definition from the comments to this class), you must override this method. You also may override this method, if it is possible to provide better performance than the default implementation, for example, for some specific variants of the aperture shape pattern.

      If the element type of dest matrix is not floating-point, then this method casts the floating-point result of the processing function g to the types of dest elements. The rules of casting depend on implementation and usually are the same as in asProcessed method. The default implementation does not need casting, because all necessary casting is already performed by asProcessed method.

      The concrete algorithm, implementing by this class, can require some number of additional arguments Mk. If the number of matrices in the passed list additionalMatrices is less than the required one, this method throws IllegalArgumentException. If the number of passed matrices is greater than the required one, it is not an error: the extra arguments are ignored.

      The aperture shape pattern, passed to this method, is automatically rounded to the nearest integer pattern by the operators pattern = pattern.round() in the very beginning of this method. In other words, this class is designed for processing integer aperture shapes only. It is the a normal situation for most aperture matrix processing algorithms.

      Overrides:
      process in class StreamingApertureProcessor
      Parameters:
      dest - the resulting matrix R.
      src - the source matrix M.
      additionalMatrices - the additional matrices M0, M1, ..., MK−1.
      pattern - the aperture shape P.