Package net.algart.arrays

Class Matrix.ContinuationMode

java.lang.Object
net.algart.arrays.Matrix.ContinuationMode
Enclosing interface:
Matrix<T extends Array>
public static class Matrix.ContinuationMode extends Object

Continuation mode for submatrices, created by Matrix.subMatrix(long[], long[], ContinuationMode continuationMode), Matrix.subMatr(long[], long[], ContinuationMode continuationMode) and similar methods. The continuation mode is passed to those methods as the last argument and specifies, what will be the values of elements of the returned submatrix, which lie outside the original matrix. (This argument is not important if all submatrix elements belong to the original matrix, i.e. if the returned matrix is a true sub-matrix of the original one.)

The following continuation modes are possible:

  • NONE: continuation is not allowed;
  • CYCLIC: cyclic repetition of the original matrix along all coordinates;
  • PSEUDO_CYCLIC: pseudo-cyclic (toroidal) repetition of the original matrix, corresponding to the cyclic repetition of its built-in array; most of algorithms of image processing work in accordance with this model;
  • MIRROR_CYCLIC: improved version of CYCLIC model, where the original matrix is repeated with "mirror reflecting"; this mode provides the best smoothness of continuation;
  • constant continuation: the space outside the original matrix is considered to be filled by some constant value.

See comments to these modes for more details.

Note: CYCLIC, PSEUDO_CYCLIC and MIRROR_CYCLIC modes are not applicable for matrices with zero dimensions: if some matrix dimension dim(k)==0, then the corresponding coordinate range of a submatrix must be 0..0, as for NONE continuation mode. See more details in comments to Matrix.subMatrix(long[], long[], ContinuationMode) method.

This class is immutable and thread-safe: there are no ways to modify settings of the created instance. Moreover, the constants NONE, CYCLIC, PSEUDO_CYCLIC, MIRROR_CYCLIC, NULL_CONSTANT, ZERO_CONSTANT, NAN_CONSTANT, as well as constants in standard Java enumerations, are unique instances, which cannot be equal to any other instance of this class. So, you can use == Java operator to compare objects with these constants, instead of calling equals(Object) method of this class.

  • Field Details

    • NONE

      public static Matrix.ContinuationMode NONE
      Simplest continuation mode: any continuation outside the source matrix is disabled.

      In this mode, the element of the returned submatrix with coordinates i0,i1,...,in-1 always corresponds to the element of the source matrix m with the coordinates p0+i0,p1+i1, ..., pn-1+in-1, where p0,p1,...,pn-1 are the low endpoints of all coordinates of the submatrix, passed as the first argument of Matrix.subMatrix(long[], long[], ContinuationMode) or Matrix.subMatr(long[], long[], ContinuationMode) method). An attempt to read this element of the submatrix returns the corresponding element of the source matrix m, and an attempt to write into this element of the submatrix modifies the corresponding element of the source matrix m.

      In a case of this mode, Matrix.subMatrix(long[], long[], ContinuationMode continuationMode) method is strictly equivalent to more simple Matrix.subMatrix(long[], long[]), and Matrix.subMatr(long[], long[], ContinuationMode continuationMode) is strictly equivalent to more simple Matrix.subMatr(long[], long[]). In other words, all submatrix elements must lie inside the original matrix, i.e. the returned matrix must be a true sub-matrix of the original one. An attempt to create a submatrix with this continuation mode, which does not lie fully inside the original matrix, leads to IndexOutOfBoundsException.

    • CYCLIC

      public static Matrix.ContinuationMode CYCLIC
      The cyclic (or true-cyclic) continuation mode.

      In this mode, the element of the returned submatrix with coordinates i0,i1,...,in-1 corresponds to the element of the built-in array m.array() of the source matrix m with the index m.cyclicIndex(p0+i0,p1+i1, ..., pn-1+in-1), where p0,p1,...,pn-1 are the low endpoints of all coordinates of the submatrix, passed as the first argument of Matrix.subMatrix(long[], long[], ContinuationMode) or Matrix.subMatr(long[], long[], ContinuationMode) method. An attempt to read this element of the submatrix returns the corresponding element of the source matrix m, and an attempt to write into this element of the submatrix modifies the corresponding element of the source matrix m.

      In other words, in this mode you can consider that the resulting matrix is a submatrix of an infinite "matrix", which is come out from the original matrix by infinite periodical repeating along all coordinate axes.

    • PSEUDO_CYCLIC

      public static Matrix.ContinuationMode PSEUDO_CYCLIC
      The pseudo-cyclic (or toroidal) continuation mode.

      In this mode, the element of the returned submatrix with coordinates i0,i1,...,in-1 corresponds to the element of the built-in array m.array() of the source matrix m with the index m.pseudoCyclicIndex(p0+i0,p1+i1, ..., pn-1+in-1), where p0,p1,...,pn-1 are the low endpoints of all coordinates of the submatrix, passed as the first argument of Matrix.subMatrix(long[], long[], ContinuationMode) or Matrix.subMatr(long[], long[], ContinuationMode) method. An attempt to read this element of the submatrix returns the corresponding element of the source matrix m, and an attempt to write into this element of the submatrix modifies the corresponding element of the source matrix m.

      In other words, in this mode you can consider that the resulting matrix is a submatrix of an infinite "matrix", which is come out from the original matrix by infinite periodical repeating its built-in array. It is the most natural mode for many image processing algorithms, which work directly with the built-in array instead of working with coordinates of matrix elements.

    • MIRROR_CYCLIC

      public static Matrix.ContinuationMode MIRROR_CYCLIC
      The mirror-cyclic continuation mode.

      In this mode, the element of the returned submatrix with coordinates i0,i1,...,in-1 corresponds to the element of the built-in array m.array() of the source matrix m with the index m.mirrorCyclicIndex(p0+i0,p1+i1, ..., pn-1+in-1), where p0,p1,...,pn-1 are the low endpoints of all coordinates of the submatrix, passed as the first argument of Matrix.subMatrix(long[], long[], ContinuationMode) or Matrix.subMatr(long[], long[], ContinuationMode) method. An attempt to read this element of the submatrix returns the corresponding element of the source matrix m, and an attempt to write into this element of the submatrix modifies the corresponding element of the source matrix m.

      In other words, in this mode you can consider that the resulting matrix is a submatrix of an infinite "matrix", which is come out from the original matrix by infinite periodical repeating along all coordinate axes, if, while every "odd" repeating, the matrix is symmetrically reflected along the corresponding coordinate. In other words, it's possible to say that the matrix is infinitely reflected in each its bound as in a mirror. Usually this mode provides the best smoothness of continuation of the matrix.

    • NULL_CONSTANT

      public static Matrix.ContinuationMode NULL_CONSTANT
      The special case of constant continuation mode, corresponding to continuing by null constant. Strictly equivalent to getConstantMode(null) (such a call always returns the reference to this constant).

      Note: unlike ZERO_CONSTANT, this mode can be used with any element type of the original matrix, including non-primitive objects. For matrices with primitive element type, this mode is equivalent to ZERO_CONSTANT.

    • ZERO_CONSTANT

      public static Matrix.ContinuationMode ZERO_CONSTANT
      The special popular case of constant continuation mode, corresponding to continuing by 0.0d numeric constant. Strictly equivalent to getConstantMode(new Double(0.0d)) (such a call always returns the reference to this constant).

      Note: unlike NULL_CONSTANT, this mode can be used only with matrices, containing elements of some primitive type, i.e. with Matrix<? extends PArray>.

    • NAN_CONSTANT

      public static Matrix.ContinuationMode NAN_CONSTANT
      The special popular case of constant continuation mode, corresponding to continuing by Double.NaN numeric constant. Strictly equivalent to getConstantMode(new Double(Double.NaN)) (such a call always returns the reference to this constant).

      Note: unlike NULL_CONSTANT, this mode can be used only with matrices, containing elements of some primitive type, i.e. with Matrix<? extends PArray>.

  • Method Details

    • getConstantMode

      public static Matrix.ContinuationMode getConstantMode(Object continuationConstant)
      Creates an instance of this class for constant continuation mode.

      In this mode, the element of the returned submatrix with coordinates i0,i1,...,in-1 corresponds to the element of the source matrix m with the coordinates p0+i0,p1+i1, ..., pn-1+in-1 (where p0,p1,...,pn-1 are the low endpoints of all coordinates of the submatrix, passed as the first argument of Matrix.subMatrix(long[], long[], ContinuationMode) or Matrix.subMatr(long[], long[], ContinuationMode) method) — if this element lies inside the source matrix. In this case, an attempt to read this element of the submatrix returns the corresponding element of the source matrix m, and an attempt to write into this element of the submatrix modifies the corresponding element of the source matrix m. In other case (if this element lies outside the source matrix), the element is considered to be equal continuationConstant (an argument of this method): an attempt to read it returns this constant, and an attempt to write into this element is just ignored.

      In other words, in this mode, you can consider that the resulting matrix is a submatrix of an infinite "matrix", which is come out from the original matrix by infinite appending it along all coordinates with the specified continuation constant.

      The argument continuationConstant of this method is automatically cast to the type of elements of the source matrix m according the following rules.

      For non-primitive element types, the continuationConstant argument must be some instance of the class m.Matrix.elementType(), or its superclass, or null. So, the type cast is trivial here.

      For primitive element types, continuationConstant may be null or any wrapper for primitive types: Boolean, Character, Byte, Short, Integer, Long, Float, Double. In this case, the following casting rules are used while reading elements (I remind that attempts to write outside the original matrix are ignored), depending on the primitive type m.Matrix.elementType():

      • null is converted to false for bit elements or to zero (0, (char)0, 0.0) for all other element types (so, it is the only universal continuation constant, which can be used with any element type: see NULL_CONSTANT);
      • if the wrapper type corresponds to the element primitive type, the trivial default conversion is used; in all other cases:
      • Boolean value v is converted to v?1:0 for numeric element types and to v?(char)1:(char)0 for char element type;
      • Character value v is converted to (byte)v, (short)v, (int)v, (long)v, (float)v, (double)v for corresponding numeric element types and to v!=0 for boolean element type;
      • Byte value v is converted to (char)(v&0xFF), (short)(v&0xFF), (int)(v&0xFF), (long)(v&0xFF), (float)(v&0xFF), (double)(v&0xFF) for corresponding numeric or character element types and to v!=0 for boolean element type;
      • Short value v is converted to (char)v, (byte)v, (int)(v&0xFFFF), (long)(v&0xFFFF), (float)(v&0xFFFF), (double)(v&0xFFFF) for corresponding numeric or character element types and to v!=0 for boolean element type;
      • Integer, Long, Float or Double value v is converted to (char)v, (byte)v, (short)v, (int)v, (long)v, (float)v, (double)v for corresponding numeric or character element types and to v!=0 for boolean element type.
      Parameters:
      continuationConstant - the value returned while reading elements, lying outside this matrix.
      Returns:
      new continuation mode with the specified continuation constant.

    • isConstant

      public boolean isConstant()
      Returns true if and only if this instance is a constant continuation mode, i.e. was created by getConstantMode(Object) method or it is one of the predefined constants ZERO_CONSTANT and NULL_CONSTANT.
      Returns:
      whether it is a constant continuation mode.

    • isPrimitiveTypeOrNullConstant

      public boolean isPrimitiveTypeOrNullConstant()
      Returns true if and only if isConstant() returns true and the result of continuationConstant() is null or is an instance of some wrapper for primitive types: Boolean, Character, Byte, Short, Integer, Long, Float or Double.

      This method indicates, whether this mode can be used for constant continuation of a matrix with primitive type of elements. But note that such a mode can also be used for continuation of a matrix, consisting of non-primitive elements, belonging to the corresponding wrapper type or its superclass like Number or Object.

      Returns:
      whether it is a constant continuation mode, where the continuation constant is null or some Java wrapper object for a primitive type.

    • continuationConstant

      public Object continuationConstant()
      Returns the continuation constant, used in this mode, if it is a constant continuation mode, or throws throws NonConstantMatrixContinuationModeException, if it is not a constant continuation mode.

      If this instance was created by getConstantMode(Object) method, this method returns exactly the same reference to an object, which was passed to that method as continuationConstant argument. For NULL_CONSTANT, this method returns null. For ZERO_CONSTANT, this method returns Double.valueOf(0.0d). For NAN_CONSTANT, this method returns Double.valueOf(Double.NaN).

      Returns:
      the continuation constant, used in this mode, if it is a constant continuation mode,
      Throws:
      NonConstantMatrixContinuationModeException - if this mode is not a constant continuation mode.
      See Also:

    • toString

      public String toString()
      Returns a brief string description of this object.

      The result of this method may depend on implementation.

      Overrides:
      toString in class Object
      Returns:
      a brief string description of this object.

    • hashCode

      public int hashCode()
      Returns the hash code of this object.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code of this object.

    • equals

      public boolean equals(Object o)
      Indicates whether some continuation mode is equal to this instance.

      If the argument is null or not an instance of this class, this method returns false.

      If this instance is a constant continuation mode, this method returns true if and only if the argument is also a constant continuation mode and either both continuation constants, returned by continuationConstant() method, are null, or they are equal objects in terms of standard equals method (i.e. equal method of the continuationConstant() object returns true for ((ContinuationMode)o).continuationConstant()).

      If this instance is not a constant continuation mode, this method returns true if and only if this instance and o argument are the same reference (this==o). It is correct, because all only possible non-constant instances of this class are represented by static constants of this class, as well as in standard enumerations.

      Overrides:
      equals in class Object
      Parameters:
      o - the object to be compared for equality with this instance.
      Returns:
      true if the specified object is a continuation mode equal to this one.