public static class Matrix.ContinuationMode
extends java.lang.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.
Modifier and Type | Field and Description |
---|---|
static Matrix.ContinuationMode |
CYCLIC
The cyclic (or true-cyclic) continuation mode.
|
static Matrix.ContinuationMode |
MIRROR_CYCLIC
The mirror-cyclic continuation mode.
|
static Matrix.ContinuationMode |
NAN_CONSTANT
The special popular case of constant continuation mode, corresponding to continuing by
Double.NaN numeric constant.
|
static Matrix.ContinuationMode |
NONE
Simplest continuation mode: any continuation outside the source matrix is disabled.
|
static Matrix.ContinuationMode |
NULL_CONSTANT
The special case of constant continuation mode, corresponding to continuing by null
constant.
|
static Matrix.ContinuationMode |
PSEUDO_CYCLIC
The pseudo-cyclic (or toroidal) continuation mode.
|
static Matrix.ContinuationMode |
ZERO_CONSTANT
The special popular case of constant continuation mode, corresponding to continuing by 0.0d
numeric constant.
|
Modifier and Type | Method and Description |
---|---|
java.lang.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. |
boolean |
equals(java.lang.Object o)
Indicates whether some continuation mode is equal to this instance.
|
static Matrix.ContinuationMode |
getConstantMode(java.lang.Object continuationConstant)
Creates an instance of this class for constant continuation mode.
|
int |
hashCode()
Returns the hash code of this object.
|
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 . |
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. |
java.lang.String |
toString()
Returns a brief string description of this object.
|
public static Matrix.ContinuationMode NONE
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
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.
public static Matrix.ContinuationMode CYCLIC
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 cyclicIndex
(p0+i0,p1+i1,
..., pn-1+in-1)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.
public static Matrix.ContinuationMode PSEUDO_CYCLIC
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 pseudoCyclicIndex
(p0+i0,p1+i1,
..., pn-1+in-1)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.
public static Matrix.ContinuationMode MIRROR_CYCLIC
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 mirrorCyclicIndex
(p0+i0,p1+i1,
..., pn-1+in-1)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.
public static Matrix.ContinuationMode NULL_CONSTANT
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
.
public static Matrix.ContinuationMode ZERO_CONSTANT
getConstantMode(new Double(0.0d))
Note: unlike NULL_CONSTANT
, this mode can be used only with matrices, containing elements of
some primitive type, i.e. with Matrix
<? extends PArray
>
public static Matrix.ContinuationMode NAN_CONSTANT
getConstantMode(new Double(Double.NaN))
Note: unlike NULL_CONSTANT
, this mode can be used only with matrices, containing elements of
some primitive type, i.e. with Matrix
<? extends PArray
>
public static Matrix.ContinuationMode getConstantMode(java.lang.Object continuationConstant)
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
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 Matrix.elementType()
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 Matrix.elementType()
NULL_CONSTANT
);continuationConstant
- the value returned while reading elements, lying outside this matrix.public boolean isConstant()
getConstantMode(Object)
method or it is one
of the predefined constants ZERO_CONSTANT
and NULL_CONSTANT
.public boolean isPrimitiveTypeOrNullConstant()
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.
public java.lang.Object continuationConstant()
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).
constant continuation mode
,NonConstantMatrixContinuationModeException
- if this mode is not a constant continuation mode.isConstant()
public java.lang.String toString()
The result of this method may depend on implementation.
toString
in class java.lang.Object
public int hashCode()
hashCode
in class java.lang.Object
public boolean equals(java.lang.Object o)
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.
equals
in class java.lang.Object
o
- the object to be compared for equality with this instance.