public class ContinuedConvolution extends java.lang.Object implements Convolution
The filter allowing to transform any Convolution
object to another instance of that interface,
which uses some nontrivial form of continuation outside the source matrix.
This object is built on the base of some parent object,
implementing Convolution
, 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 pseudocyclic continuation.
More precisely, all methods of this object call the corresponding methods of the parent one.
But before calling any processing method, the source matrix 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
.
So, all dimensions of the appended matrix are little greater than the corresponding dimensions
of the source one, and extra elements are (virtually) filled by some values according the given continuation mode.
The size of extension along all coordinates depends on the pattern and the performed operation.
After this, the corresponding method of parent object processes the appended matrix,
and the method of this class returns the corresponding submatrix of the result, with dimensions, equal
to the dimensions of the source matrix.
The processing is little different for the method
convolution(Matrix, Matrix, WeightedPattern)
,
placing the result into the first argument.
In this case, the destination (updatable) matrix is (virtually) extended like the source 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 destination 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: Matrix.ContinuationMode.NONE
continuation mode cannot be used in this class:
such value of continuationMode argument of the instantiation method
getInstance(Convolution, Matrix.ContinuationMode)
leads
to IllegalArgumentException.
Note: in improbable cases, when the dimensions of the source matrix and/or
the sizes of the pattern are extremely large (about 2^{63}),
so that the necessary appended matrices should have dimensions or total number of elements,
greater than
This class is immutable and threadsafe: there are no ways to modify settings of the created instance.
Modifier and Type  Method and Description 

<T extends PArray> 
asConvolution(java.lang.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.

Matrix<? extends PArray> 
asConvolution(Matrix<? extends PArray> src,
WeightedPattern pattern)
Equivalent to
asConvolution (src.type (PArray.class), src, pattern). 
ArrayContext 
context()
Returns the current context used by this instance for all operations.

Convolution 
context(ArrayContext newContext)
Switches the context: returns an instance, identical to this one excepting
that it uses the specified newContext for all operations.

Matrix.ContinuationMode 
continuationMode()
Returns the continuation mode, used by this object for virtual continuing the source matrix.

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

void 
convolution(Matrix<? extends UpdatablePArray> dest,
Matrix<? extends PArray> src,
WeightedPattern pattern) 
static ContinuedConvolution 
getInstance(Convolution parent,
Matrix.ContinuationMode continuationMode)
Returns new instance of this class with the passed parent
Convolution object
and the specified continuation mode. 
double 
increment(java.lang.Class<?> elementType) 
boolean 
isPseudoCyclic()
Returns true, if this class works in the default
pseudocyclic continuation mode . 
Convolution 
parent()
Returns the parent
Convolution object, passed to
getInstance(Convolution, Matrix.ContinuationMode) method. 
public static ContinuedConvolution getInstance(Convolution parent, Matrix.ContinuationMode continuationMode)
Convolution
object
and the specified continuation mode.
See comments to Matrix.ContinuationMode
class
for more information about possible continuations.parent
 the instance of Convolution
interface that will perform all operations.continuationMode
 the mode of continuation outside the source matrix.java.lang.NullPointerException
 if parent or continuationMode argument is null.java.lang.IllegalArgumentException
 if continuationMode==Matrix.ContinuationMode.NONE
.parent()
,
continuationMode()
public Convolution parent()
Convolution
object, passed to
getInstance(Convolution, Matrix.ContinuationMode)
method.Convolution
object.public Matrix.ContinuationMode continuationMode()
getInstance(Convolution, Matrix.ContinuationMode)
method.public ArrayContext context()
ArrayProcessor
ArrayContext.DEFAULT
context.context
in interface ArrayProcessor
public Convolution context(ArrayContext newContext)
subtask
of the full task.context
in interface ArrayProcessorWithContextSwitching
context
in interface Convolution
newContext
 another context, used by the returned instance; may be null.public boolean isPseudoCyclic()
Convolution
pseudocyclic 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.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
.
isPseudoCyclic
in interface Convolution
public double increment(java.lang.Class<?> elementType)
increment
in interface Convolution
public Matrix<? extends PArray> asConvolution(Matrix<? extends PArray> src, WeightedPattern pattern)
Convolution
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.asConvolution
in interface Convolution
src
 the source matrix.pattern
 the pattern.public <T extends PArray> Matrix<T> asConvolution(java.lang.Class<? extends T> requiredType, Matrix<? extends PArray> src, WeightedPattern pattern)
Convolution
Convolution.convolution(Class, Matrix, WeightedPattern)
method about the "convolution" term.
The matrix, returned by this method, is immutable, and the class of its builtin 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.
asConvolution
in interface Convolution
requiredType
 desired type of the builtin array in the returned matrix.src
 the source matrix.pattern
 the pattern.public Matrix<? extends UpdatablePArray> convolution(Matrix<? extends PArray> src, WeightedPattern pattern)
Convolution
Usually convolution means the weighted sum of the set of matrices,
obtained by pseudocyclic shifting the source matrix by the vectors,
equal to all pattern points, with weights, equal to
weights
of the pattern points.
More precisely, let m_{i}=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 m_{i} matrices:
∑ w_{i}m_{i}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 nontrivial rules
instead of pseudocyclic continuation
(as in ContinuedConvolution
objects),
or only some region of the matrix may be processed, etc.
convolution
in interface Convolution
src
 the source matrix.pattern
 the pattern.Convolution.asConvolution(Class, Matrix, WeightedPattern)
public <T extends PArray> Matrix<? extends T> convolution(java.lang.Class<? extends T> requiredType, Matrix<? extends PArray> src, WeightedPattern pattern)
convolution
in interface Convolution
public void convolution(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src, WeightedPattern pattern)
convolution
in interface Convolution