Package net.algart.arrays

Class Matrices

java.lang.Object

net.algart.arrays.Matrices

public class Matrices
extends Object

Utilities useful for working with AlgART matrices.

This class cannot be instantiated.

Author:

Daniel Alievsky

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Matrices.ConvexHyperpolyhedron	Convex hyperpolyhedron: an intersection of several n-dimensional half-spaces and some hyperparallelepiped.
static final class	Matrices.Hyperparallelepiped	Hyperparallelepiped: the simplest n-dimensional region.
static enum	Matrices.InterpolationMethod	Interpolation method for representing AlgART matrix as a mathematical function.
static final class	Matrices.Polygon2D	2-dimensional polygon.
static class	Matrices.Region	Region in n-dimensional space.
static class	Matrices.ResizingMethod	Resizing mode for Matrices.asResized method.
static final class	Matrices.Simplex	Simplex: the simplest n-dimensional hyperpolyhedron with n+1 vertices.

Method Summary

Modifier and Type	Method	Description
static void	add(Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> other)	Addition: equivalent to addToOther(result, result, other).
static void	addToOther(Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> a, Matrix<? extends PArray> b)	Addition: equivalent to applyFunc(ArrayContext.DEFAULT_SINGLE_THREAD, Func.X_PLUS_Y, result, a, b).
static void	applyFunc(ArrayContext context, boolean truncateOverflows, Func f, Matrix<? extends UpdatablePArray> result, List<? extends Matrix<? extends PArray>> x)	Calls to Arrays.applyFunc(context, truncateOverflows, f, result.array(), arrays), where arrays is {x.get(0).array(), x.get(1).array(), ...}.
static void	applyFunc(ArrayContext context, boolean truncateOverflows, Func f, Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> x)	Equivalent to applyFunc(context, truncateOverflows, f, result, several(PArray.class, x)).
static void	applyFunc(ArrayContext context, boolean truncateOverflows, Func f, Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> x1, Matrix<? extends PArray> x2)	Equivalent to applyFunc(context, truncateOverflows, f, result, several(PArray.class, x1, x2)).
static void	applyFunc(ArrayContext context, boolean truncateOverflows, Func f, Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> x1, Matrix<? extends PArray> x2, Matrix<? extends PArray> x3)	Equivalent to applyFunc(context, truncateOverflows, f, result, several(PArray.class, x1, x2, x3)).
static void	applyFunc(ArrayContext context, boolean truncateOverflows, Func f, Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> x1, Matrix<? extends PArray> x2, Matrix<? extends PArray> x3, Matrix<? extends PArray> x4)	Equivalent to applyFunc(context, truncateOverflows, f, result, several(PArray.class, x1, x2, x3, x4)).
static void	applyFunc(ArrayContext context, Func f, Matrix<? extends UpdatablePArray> result, List<? extends Matrix<? extends PArray>> x)	Equivalent to applyFunc(context, true, f, result, x).
static void	applyFunc(ArrayContext context, Func f, Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> x)	Equivalent to applyFunc(context, true, f, result, x).
static void	applyFunc(ArrayContext context, Func f, Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> x1, Matrix<? extends PArray> x2)	Equivalent to applyFunc(context, true, f, result, x1, x2).
static void	applyFunc(ArrayContext context, Func f, Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> x1, Matrix<? extends PArray> x2, Matrix<? extends PArray> x3)	Equivalent to applyFunc(context, true, f, result, x1, x2, x3).
static void	applyFunc(ArrayContext context, Func f, Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> x1, Matrix<? extends PArray> x2, Matrix<? extends PArray> x3, Matrix<? extends PArray> x4)	Equivalent to applyFunc(context, true, f, result, x1, x2, x3, x4).
static void	applyFunction(ArrayContext context, DoubleUnaryOperator function, Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> source)	Performs the specified function for all elements of source to produce result.
static void	applyPrecision(ArrayContext context, Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> matrix)	Equivalent to creating a "lazy" matrix by lazy = asPrecision(matrix, result.elementType() call and copying it into the result argument by copy(context, result, lazy) call.
static void	applyPredicate(ArrayContext context, DoublePredicate predicate, Matrix<? extends UpdatableBitArray> result, Matrix<? extends PArray> source)	Performs the specified predicate for all elements of source to produce result.
static <T extends Array> T[]	arraysOfParallelMatrices(Class<T> arrayClass, Collection<? extends Matrix<?>> matrices, boolean requireIdenticalType)	Equivalent of arraysOfParallelMatrices(Class, List) method, but, if requireIdenticalType=true, also checks that all passed matrices have identical element type.
static <T extends Array> T[]	arraysOfParallelMatrices(Class<T> arrayClass, List<? extends Matrix<?>> matrices)	Checks whether all passed matrices are not null and have equal dimensions and, if it is true, creates and returns Java array of built-in AlgART arrays of all passed matrices.
static <T extends PArray> Matrix<T>	asCoordFuncMatrix(boolean truncateOverflows, Func f, Class<? extends T> requiredType, long... dim)	An analog of the asFuncMatrix(boolean, Func, Class, List) method, where the passed function is applied not to the elements of some source matrices, but to the indexes of the resulting matrix.
static <T extends PArray> Matrix<T>	asCoordFuncMatrix(Func f, Class<? extends T> requiredType, long... dim)	Equivalent to asCoordFuncMatrix(true, f, requiredType, dim).
static <T extends PArray> Matrix<T>	asFuncMatrix(boolean truncateOverflows, Func f, Class<? extends T> requiredType, List<? extends Matrix<? extends PArray>> x)	An analog of Arrays.asFuncArray(boolean, Func, Class, PArray...) method for AlgART matrices.
static <T extends PArray> Matrix<T>	asFuncMatrix(boolean truncateOverflows, Func f, Class<? extends T> requiredType, Matrix<? extends PArray> x)	Equivalent to asFuncMatrix(truncateOverflows, f, requiredType, several(PArray.class, x)).
static <T extends PArray> Matrix<T>	asFuncMatrix(boolean truncateOverflows, Func f, Class<? extends T> requiredType, Matrix<? extends PArray> x1, Matrix<? extends PArray> x2)	Equivalent to asFuncMatrix(truncateOverflows, f, requiredType, several(PArray.class, x1, x2)).
static <T extends PArray> Matrix<T>	asFuncMatrix(boolean truncateOverflows, Func f, Class<? extends T> requiredType, Matrix<? extends PArray> x1, Matrix<? extends PArray> x2, Matrix<? extends PArray> x3)	Equivalent to asFuncMatrix(truncateOverflows, f, requiredType, several(PArray.class, x1, x2, x3)).
static <T extends PArray> Matrix<T>	asFuncMatrix(boolean truncateOverflows, Func f, Class<? extends T> requiredType, Matrix<? extends PArray> x1, Matrix<? extends PArray> x2, Matrix<? extends PArray> x3, Matrix<? extends PArray> x4)	Equivalent to asFuncMatrix(truncateOverflows, f, requiredType, several(PArray.class, x1, x2, x3, x4)).
static <T extends PArray> Matrix<T>	asFuncMatrix(Func f, Class<? extends T> requiredType, List<? extends Matrix<? extends PArray>> x)	Equivalent to asFuncMatrix(true, f, requiredType, x).
static <T extends PArray> Matrix<T>	asFuncMatrix(Func f, Class<? extends T> requiredType, Matrix<? extends PArray> x)	Equivalent to asFuncMatrix(f, requiredType, several(PArray.class, x)).
static <T extends PArray> Matrix<T>	asFuncMatrix(Func f, Class<? extends T> requiredType, Matrix<? extends PArray> x1, Matrix<? extends PArray> x2)	Equivalent to asFuncMatrix(f, requiredType, several(PArray.class, x1, x2)).
static <T extends PArray> Matrix<T>	asFuncMatrix(Func f, Class<? extends T> requiredType, Matrix<? extends PArray> x1, Matrix<? extends PArray> x2, Matrix<? extends PArray> x3)	Equivalent to asFuncMatrix(f, requiredType, several(PArray.class, x1, x2, x3)).
static <T extends PArray> Matrix<T>	asFuncMatrix(Func f, Class<? extends T> requiredType, Matrix<? extends PArray> x1, Matrix<? extends PArray> x2, Matrix<? extends PArray> x3, Matrix<? extends PArray> x4)	Equivalent to asFuncMatrix(f, requiredType, several(PArray.class, x1, x2, x3, x4)).
static Func	asInterpolationFunc(Matrix<? extends PArray> matrix, Matrices.InterpolationMethod interpolationMethod, boolean checkRanges)	Returns a function of the coordinates represented by the given matrix with the given interpolation method.
static Func	asInterpolationFunc(Matrix<? extends PArray> matrix, Matrices.InterpolationMethod interpolationMethod, double outsideValue)	An analog of asInterpolationFunc(Matrix, InterpolationMethod, boolean) method, that use constant continuation for all coordinates outside the matrix.
static <T extends Array> List<Matrix<T>>	asLayers(Matrix<T> merged)	Equivalent to asLayers(merged, Integer.MAX_VALUE) (no limitations).
static <T extends Array> List<Matrix<T>>	asLayers(Matrix<T> merged, int limit)	Splits a single (n+1)-dimensional matrix M0xM1x...xMn to Mn separate n-dimensional matrices M0xM1x...xMn−1 and returns them as a list.
static Matrix<? extends PArray>	asPrecision(Matrix<? extends PArray> matrix, Class<?> newElementType)	Returns an immutable view of the passed AlgART matrix, cast to another primitive element type (other precision) with automatic scaling, so that 0.0 is cast to 0.0 and maximal possible value of the source matrix is scaled to maximal possible value of the result.
static Matrix<PArray>	asResized(Matrices.ResizingMethod resizingMethod, Matrix<? extends PArray> matrix, long... newDim)	Returns an immutable view of the passed AlgART matrix, resized to the specified dimensions newDim.
static Matrix<PArray>	asResized(Matrices.ResizingMethod resizingMethod, Matrix<? extends PArray> matrix, long[] newDim, double[] scales)	An extended analog of asResized(Matrices.ResizingMethod, Matrix, long...) method, allowing to precisely specify a custom scaling value along every coordinate.
static Matrix<Array>	asShifted(Matrix<? extends Array> matrix, long... shifts)	Returns an immutable view of the passed AlgART matrix, pseudo-cyclically shifted to the right for every coordinate.
static <T extends UpdatablePArray> Matrix<T>	asUpdatableFuncMatrix(boolean truncateOverflows, Func.Updatable f, Class<? extends T> requiredType, Matrix<? extends UpdatablePArray> x)	An analog of Arrays.asUpdatableFuncArray method for AlgART matrices.
static <T extends UpdatablePArray> Matrix<T>	asUpdatableFuncMatrix(Func.Updatable f, Class<? extends T> requiredType, Matrix<? extends UpdatablePArray> x)	Equivalent to asUpdatableFuncMatrix(true, f, requiredType, x).
static void	bitAnd(Matrix<? extends UpdatableBitArray> result, Matrix<? extends BitArray> other)	Binary AND: equivalent to bitAndToOther(result, result, other).
static void	bitAndToOther(Matrix<? extends UpdatableBitArray> result, Matrix<? extends BitArray> a, Matrix<? extends BitArray> b)	Binary AND: equivalent to applyFunc(ArrayContext.DEFAULT_SINGLE_THREAD, Func.MIN, result, a, b).
static void	bitDiff(Matrix<? extends UpdatableBitArray> result, Matrix<? extends BitArray> other)	Binary AND-NOT: equivalent to bitDiffToOther(result, result, other).
static void	bitDiffToOther(Matrix<? extends UpdatableBitArray> result, Matrix<? extends BitArray> a, Matrix<? extends BitArray> b)	Binary AND-NOT: equivalent to applyFunc(ArrayContext.DEFAULT_SINGLE_THREAD, Func.POSITIVE_DIFF, result, a, b).
static void	bitNot(Matrix<? extends UpdatableBitArray> bitMatrix)	Binary NOT: equivalent to bitNotToOther(bitMatrix, bitMatrix).
static void	bitNotToOther(Matrix<? extends UpdatableBitArray> result, Matrix<? extends BitArray> source)	Binary NOT: equivalent to applyFunc(ArrayContext.DEFAULT_SINGLE_THREAD, Func.REVERSE, result, source).
static void	bitOr(Matrix<? extends UpdatableBitArray> result, Matrix<? extends BitArray> other)	Binary OR: equivalent to bitOrToOther(result, result, other).
static void	bitOrToOther(Matrix<? extends UpdatableBitArray> result, Matrix<? extends BitArray> a, Matrix<? extends BitArray> b)	Binary OR: equivalent to applyFunc(ArrayContext.DEFAULT_SINGLE_THREAD, Func.MAX, result, a, b).
static void	bitXor(Matrix<? extends UpdatableBitArray> result, Matrix<? extends BitArray> other)	Binary XOR: equivalent to bitXorToOther(result, result, other).
static void	bitXorToOther(Matrix<? extends UpdatableBitArray> result, Matrix<? extends BitArray> a, Matrix<? extends BitArray> b)	Binary XOR: equivalent to applyFunc(ArrayContext.DEFAULT_SINGLE_THREAD, Func.ABS_DIFF, result, a, b).
static void	checkDimensionEquality(Collection<? extends Matrix<?>> matrices)	Checks whether all passed matrices are not null and have equal dimensions and, it is not so, throws a corresponding exception.
static void	checkDimensionEquality(Collection<? extends Matrix<?>> matrices, boolean requireIdenticalType)	Checks the same condition as checkDimensionEquality(Collection) and, if requireIdenticalType=true, also checks that all passed matrices have identical element type.
static void	checkDimensionEquality(Matrix<?>... matrices)	Checks whether all passed matrices are not null and have equal dimensions and, it is not so, throws a corresponding exception.
static <T extends Array> void	checkNewMatrixType(Class<T> arraySupertype, Class<?> elementType)	Checks whether the passed arraySupertype is one of 18 basic non-mutable array types BitArray.class, CharArray.class, ByteArray.class, ShortArray.class, IntArray.class, LongArray.class, FloatArray.class, DoubleArray.class, ObjectArray.class, UpdatableBitArray.class, UpdatableCharArray.class, UpdatableByteArray.class, UpdatableShortArray.class, UpdatableIntArray.class, UpdatableLongArray.class, UpdatableFloatArray.class, UpdatableDoubleArray.class, UpdatableObjectArray.class, suitable for storing the specified element type.
static void	clear(Matrix<? extends UpdatablePArray> result)	Fills all elements of the matrix with zero value.
static void	clearBoundary(Matrix<? extends UpdatablePArray> result, int boundaryWidth)	Equivalent to fillBoundary(result, boundaryWidth, 0.0).
static Matrix<? extends UpdatablePArray>	clone(Matrix<? extends PArray> matrix)	Equivalent to clone(matrix, Arrays.SMM).
static Matrix<? extends UpdatablePArray>	clone(MemoryModel memoryModel, Matrix<? extends PArray> matrix)	Returns an exact updatable clone of the given matrix, created in the given memory model.
static Arrays.ComparingCopyStatus	compareAndCopy(ArrayContext context, Matrix<? extends UpdatableArray> dest, Matrix<? extends Array> src)	This method just calls Arrays.compareAndCopy(context, dest.array(), src.array()), if the passed matrices have the same dimensions, or throws SizeMismatchException in other case.
static <T extends PArray> Matrix<T>	constantMatrix(double constant, Class<? extends T> requiredType, long... dim)	Returns a constant matrix, filled by the specified constant.
static Arrays.CopyStatus	copy(ArrayContext context, Matrix<? extends UpdatableArray> dest, Matrix<? extends Array> src)	This method just calls Arrays.copy(context, dest.array(), src.array()), if the passed matrices have the same dimensions, or throws SizeMismatchException in other case.
static Arrays.CopyStatus	copy(ArrayContext context, Matrix<? extends UpdatableArray> dest, Matrix<? extends Array> src, int numberOfTasks)	This method just calls Arrays.copy(context, dest.array(), src.array(), numberOfTasks), if the passed matrices have the same dimensions, or throws SizeMismatchException in other case.
static Arrays.CopyStatus	copy(ArrayContext context, Matrix<? extends UpdatableArray> dest, Matrix<? extends Array> src, int numberOfTasks, boolean strictMode)	This method just calls Arrays.copy(context, dest.array(), src.array(), numberOfTasks, strictMode), if the passed matrices have the same dimensions, or throws SizeMismatchException in other case.
static void	copy(Matrix<? extends UpdatablePArray> dest, Matrix<? extends PArray> src)	Just copies src into dest without using multithreading.
static void	copyRegion(ArrayContext context, Matrix<? extends UpdatableArray> dest, Matrix<? extends Array> src, Matrices.Region destRegion, long... shifts)	Copies the specified region from src AlgART matrix to dest AlgART matrix.
static void	copyRegion(ArrayContext context, Matrix<? extends UpdatableArray> dest, Matrix<? extends Array> src, Matrices.Region destRegion, long[] shifts, Object outsideValue)	An extended analog of copyRegion(ArrayContext, Matrix, Matrix, Region, long...) method, allowing to copy regions which do not lie fully inside dest and src matrices.
static long[]	defaultTileDimensions(int dimCount)	Returns default dimensions of a tile, used by Matrix.tile() method to create a tiled matrix.
static String	dimensionsToString(long[] dim)
static void	fill(Matrix<? extends UpdatablePArray> result, double value)	Fills all elements of the matrix with the specified value.
static void	fillBoundary(Matrix<? extends UpdatablePArray> result, int boundaryWidth, double value)	Fills the boundary result matrix with the given width with the specified value..
static void	fillOutside(Matrix<? extends UpdatablePArray> result, long minX, long minY, long sizeX, long sizeY, double value)	Fills all result matrix, excepting elements in the rectangle minX≤x<minX+sizeX, minY≤y<minY+sizeY, with the specified value.
static void	fillRegion(ArrayContext context, Matrix<? extends UpdatableArray> dest, Matrices.Region destRegion, Object value)	Fills the specified region in dest AlgART matrix with the specified value.
static Matrices.InterpolationMethod	getInterpolationMethod(Func f)	If the passed function is an interpolation view of some AlgART matrix, returns the interpolation algorithm, used while creating this function.
static double	getOutsideValue(Func f)	If the passed function is a continued interpolation view of an AlgART matrix, return the value used outside the matrix.
static Matrix<? extends PArray>	getUnderlyingMatrix(Func f)	If the passed function is an interpolation view of an AlgART matrix, returns the reference to this matrix.
static <T extends PArray> Matrix<T>	interleave(ArrayContext context, List<? extends Matrix<? extends T>> separated)	Merges (interleaves) K n-dimensional matrices with identical element types and dimensions M1x...xMn, passed in the separated list, into a single (n+1)-dimensional matrix KxM1x...xMn along the first dimension.
static void	interleave(ArrayContext context, Matrix<? extends UpdatablePArray> result, List<? extends Matrix<? extends PArray>> separated)	Analog of interleave(ArrayContext, List) method, that does not allocate memory, but stores the results into previously created result matrix.
static boolean	isCheckedOnlyInsideInterpolationFunc(Func f)	Returns true if the passed function is not null interpolation view of an AlgART matrix, created by asInterpolationFunc(Matrix, InterpolationMethod, boolean) method with true last argument.
static boolean	isContinuedInterpolationFunc(Func f)	Returns true if the passed function is not null interpolation view of an AlgART matrix, created by asInterpolationFunc(Matrix, InterpolationMethod, double) method.
static boolean	isCoordFuncMatrix(Matrix<? extends PArray> matrix)	Returns true if the passed matrix is not null functional matrix, created by this package, calculated on the base of coordinates only, not depending on another arrays/matrices.
static boolean	isInterpolationFunc(Func f)	Returns true if the passed function is not null interpolation view of an AlgART matrix, created by this package.
static boolean	isOnlyInsideInterpolationFunc(Func f)	Returns true if the passed function is not null interpolation view of an AlgART matrix, created by asInterpolationFunc(Matrix, InterpolationMethod, boolean) method.
static <T extends Array> Matrix<T>	matrix(T array, long... dim)	Returns new matrix (multi-dimensional array), backed by the specified AlgART array, with the given dimensions.
static <T extends Array> Matrix<T>	matrixAtSubArray(T array, long position, long... dim)	Returns new matrix (multi-dimensional array) with the given dimensions, backed by the part of the specified AlgART array, starting from the given position.
static <T extends Array> Matrix<T>	mergeLayers(MemoryModel memoryModel, List<? extends Matrix<? extends T>> matrices)	Merges (concatenates) K n-dimensional matrices with identical element types and dimensions M0xM1x...xMn−1, passed in the matrices list, into a single (n+1)-dimensional matrix M0xM1x...xMn−1xK along the last dimension.
static void	packBitsGreater(Matrix<? extends UpdatableBitArray> result, Matrix<? extends PArray> intensities, double threshold)	Equivalent to packBitsGreater(result.array(), intensities.array(), threshold)
static void	packBitsGreaterOrEqual(Matrix<? extends UpdatableBitArray> result, Matrix<? extends PArray> intensities, double threshold)	Equivalent to packBitsGreaterOrEqual(result.array(), intensities.array(), threshold)
static void	packBitsLess(Matrix<? extends UpdatableBitArray> result, Matrix<? extends PArray> intensities, double threshold)	Equivalent to packBitsLess(result.array(), intensities.array(), threshold)
static void	packBitsLessOrEqual(Matrix<? extends UpdatableBitArray> result, Matrix<? extends PArray> intensities, double threshold)	Equivalent to packBitsLessOrEqual(result.array(), intensities.array(), threshold)
static void	resize(ArrayContext context, Matrices.ResizingMethod resizingMethod, Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> src)	Resizes the source matrix to the dimensions of the passed result matrix and stores the resized matrix in result argument.
static void	separate(ArrayContext context, List<? extends Matrix<? extends UpdatablePArray>> result, Matrix<? extends PArray> interleaved)	Analog of separate(ArrayContext, Matrix) method, that does not allocate memory, but stores the results into previously created list of matrices.
static <T extends PArray> List<Matrix<T>>	separate(ArrayContext context, Matrix<? extends T> interleaved)	Equivalent to separate(context, interleaved, Integer.MAX_VALUE) (no limitations).
static <T extends PArray> List<Matrix<T>>	separate(ArrayContext context, Matrix<? extends T> interleaved, int limit)	Splits a single (n+1)-dimensional interleaved matrix M0xM1x...xMn along dimension #0 to M0 separate n-dimensional matrices M1x...xMn and returns them as a list.
static <T extends Array> List<Matrix<? extends T>>	several(Class<T> arrayClass, Matrix<?>... matrices)	Returns an updatable list java.util.Arrays.asList(matrices.clone()), if all these matrices are not null and all their built-in arrays matrices[k].array() are instances of the required arrayClass, or throws an exception in other case.
static <T extends Array> double	sizeOf(Collection<Matrix<? extends T>> matrices)	Estimates the summary size (in bytes) of all the matrices in the passed collection.
static long	sizeOf(Matrix<?> matrix)	Estimates the size (in bytes) of the matrix.
static void	subtract(Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> other)	Subtraction: equivalent to subtractToOther(result, result, other).
static void	subtractToOther(Matrix<? extends UpdatablePArray> result, Matrix<? extends PArray> a, Matrix<? extends PArray> b)	Subtraction: equivalent to applyFunc(ArrayContext.DEFAULT_SINGLE_THREAD, Func.X_MINUS_Y, result, a, b).
static byte[]	toByteJavaArray(byte[] result, Matrix<? extends PArray> matrix)	Equivalent to Arrays.toByteJavaArray(result, matrix.array()).
static byte[]	toByteJavaArray(Matrix<? extends PArray> matrix)	Equivalent to Arrays.toByteJavaArray(matrix.array()).
static double[]	toDoubleJavaArray(double[] result, Matrix<? extends PArray> matrix)	Equivalent to Arrays.toDoubleJavaArray(result, matrix.array()).
static double[]	toDoubleJavaArray(Matrix<? extends PArray> matrix)	Equivalent to Arrays.toDoubleJavaArray(matrix.array()).
static float[]	toFloatJavaArray(float[] result, Matrix<? extends PArray> matrix)	Equivalent to Arrays.toFloatJavaArray(result, matrix.array()).
static float[]	toFloatJavaArray(Matrix<? extends PArray> matrix)	Equivalent to Arrays.toFloatJavaArray(matrix.array()).
static int[]	toIntJavaArray(int[] result, Matrix<? extends PArray> matrix)	Equivalent to Arrays.toIntJavaArray(result, matrix.array()).
static int[]	toIntJavaArray(Matrix<? extends PArray> matrix)	Equivalent to Arrays.toIntJavaArray(matrix.array()).
static long[]	toLongJavaArray(long[] result, Matrix<? extends PArray> matrix)	Equivalent to Arrays.toLongJavaArray(result, matrix.array()).
static long[]	toLongJavaArray(Matrix<? extends PArray> matrix)	Equivalent to Arrays.toLongJavaArray(matrix.array()).
static short[]	toShortJavaArray(short[] result, Matrix<? extends PArray> matrix)	Equivalent to Arrays.toShortJavaArray(result, matrix.array()).
static short[]	toShortJavaArray(Matrix<? extends PArray> matrix)	Equivalent to Arrays.toShortJavaArray(matrix.array()).
static void	unpackBits(Matrix<? extends UpdatablePArray> result, Matrix<? extends BitArray> bits, double filler0, double filler1)	Equivalent to unpackBits(result.array(), bits.array(), filler0, filler1)
static void	unpackUnitBits(Matrix<? extends UpdatablePArray> result, Matrix<? extends BitArray> bits, double filler1)	Equivalent to unpackUnitBits(result.array(), bits.array(), filler1)
static void	unpackZeroBits(Matrix<? extends UpdatablePArray> result, Matrix<? extends BitArray> bits, double filler0)	Equivalent to unpackZeroBits(result.array(), bits.array(), filler0)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

matrix

public static <T extends Array> Matrix<T> matrix(T array,
 long... dim)

Returns new matrix (multi-dimensional array), backed by the specified AlgART array, with the given dimensions.

The array must be unresizable. The product of all dimensions (dim[0]*dim[1]*...*dim[dim.length-1]) must be equal to array.length(). The dimensions must not be negative. The Matrix.dimCount() method will return dim.length, and Matrix.dim(n) method will return dim[n].

The passed dim argument is cloned by this method: no references to it are maintained by the created matrix.

Parameters:

array - an array storing all matrix elements.

dim - the matrix dimensions.

Returns:

new matrix backed by array with the given dimensions.

Throws:

NullPointerException - if array or dim argument is null.

IllegalArgumentException - if the passed array is resizable (for example, implements MutableArray), or if the number of dimensions is 0 (empty dim Java array), or if some of the dimensions are negative.

SizeMismatchException - if the product of all dimensions is not equal to the array length.

TooLargeArrayException - if the product of all dimensions is greater than Long.MAX_VALUE.

See Also:

• MemoryModel.newMatrix(Class, Class, long...)
• matrixAtSubArray(Array, long, long...)

matrixAtSubArray

public static <T extends Array> Matrix<T> matrixAtSubArray(T array,
 long position,
 long... dim)

Returns new matrix (multi-dimensional array) with the given dimensions, backed by the part of the specified AlgART array, starting from the given position. Unlike matrix(Array, long...), this method allows to use an array, the length of which is greater than the product of all passed dimensions: its subarray with fromIndex=position will be used instead of the full array.

The array must be unresizable. The position must be in range 0..array.length(), and the product of all dimensions (dim[0]*dim[1]*...*dim[dim.length-1]) must be not greater than array.length()-position. The dimensions and the given position must not be negative. The Matrix.dimCount() method will return dim.length, and Matrix.dim(n) method will return dim[n].

This method returns the same result as the call matrix(array.subArr(position,product),dim), where product=dim[0]*dim[1]*...*dim[dim.length-1]. But subArr method is not called in a case of invalid dimensions; in this case, an exception is thrown.

The passed dim argument is cloned by this method: no references to it are maintained by the created matrix.

Parameters:

array - an array storing all matrix elements.

position - the starting position inside the array, from which the matrix elements are placed.

dim - the matrix dimensions.

Returns:

new matrix backed by array with the given dimensions.

Throws:

NullPointerException - if array or dim argument is null.

IndexOutOfBoundsException - for illegal position (position < 0 || position > array.length()).

IllegalArgumentException - if the passed array is resizable (for example, implements MutableArray), or if the number of dimensions is 0 (empty dim Java array), or if some of dimensions are negative.

SizeMismatchException - if the product of all dimensions is greater than array.length()-position.

TooLargeArrayException - if the product of all dimensions is greater than Long.MAX_VALUE.

See Also:

• MemoryModel.newMatrix(Class, Class, long...)

checkNewMatrixType

public static <T extends Array> void checkNewMatrixType(Class<T> arraySupertype,
 Class<?> elementType)

Checks whether the passed arraySupertype is one of 18 basic non-mutable array types BitArray.class, CharArray.class, ByteArray.class, ShortArray.class, IntArray.class, LongArray.class, FloatArray.class, DoubleArray.class, ObjectArray.class, UpdatableBitArray.class, UpdatableCharArray.class, UpdatableByteArray.class, UpdatableShortArray.class, UpdatableIntArray.class, UpdatableLongArray.class, UpdatableFloatArray.class, UpdatableDoubleArray.class, UpdatableObjectArray.class, suitable for storing the specified element type. In other case, throws an exception.

More precisely, this method throws ClassCastException, if !arraySupertype.isAssignableFrom(type), where type=Arrays.type(UpdatableArray.class,elementType). Before this check, this method also throws IllegalArgumentException if the passed type is mutable, i.e. if MutableArray.class.isAssignableFrom(arraySupertype). And in the very beginning this method throws an exception if one of its arguments is null or if elementType==void.class. In all other cases, this method does nothing.

This method is useful if you are planning to create a new matrix with the given element type, for example, by MemoryModel.newMatrix method, and you want to be sure that you will be able to cast it to the specified generic type Matrix<T>.

Note: unlike MemoryModel.newMatrix method, this method allows specifying non-updatable arraySupertype (for example, ByteArray.class).

Parameters:

arraySupertype - the desired type of the underlying array (the generic argument of the matrix type).

elementType - the type of matrix elements.

Throws:

NullPointerException - if elementType or dim is null.

IllegalArgumentException - if elementType is void.class or if arraySupertype is MutableArray or its subtype.

ClassCastException - if arraySupertype and elementType do not match.

sizeOf

public static long sizeOf(Matrix<?> matrix)

Estimates the size (in bytes) of the matrix. Equivalent to Arrays.sizeOf(matrix.array()).

Parameters:

matrix - some AlgART matrix.

Returns:

the estimated size of this matrix in bytes.

Throws:

NullPointerException - if the argument is null.

See Also:

• Arrays.sizeOf(Array)

sizeOf

public static <T extends Array> double sizeOf(Collection<Matrix<? extends T>> matrices)

Estimates the summary size (in bytes) of all the matrices in the passed collection. This method just calls sizeOf(Matrix) method for each element of this collection and returns the sum of the results of all these calls.

Parameters:

matrices - some collection of AlgART matrices.

Returns:

the estimated summary size of all these matrices in bytes.

Throws:

NullPointerException - if the argument is null or if one of elements of the passed collection is null.

See Also:

• Arrays.sizeOf(Array)

defaultTileDimensions

public static long[] defaultTileDimensions(int dimCount)

Returns default dimensions of a tile, used by Matrix.tile() method to create a tiled matrix.

The returned array is a newly created Java array, containing dimCount elements. The elements of the returned array are positive numbers, probably equal to each other and not too large (several hundreds or thousands).

Parameters:

dimCount - the number of dimensions of the matrix.

Returns:

an array containing all dimensions of every tile in a tiled matrix, created by Matrix.tile() method.

several

public static <T extends Array>
List<Matrix<? extends T>> several(Class<T> arrayClass,
 Matrix<?>... matrices)

Returns an updatable list java.util.Arrays.asList(matrices.clone()), if all these matrices are not null and all their built-in arrays matrices[k].array() are instances of the required arrayClass, or throws an exception in other case.

Unlike java.util.Arrays.asList method, this one allows creating a list without unchecked warnings.

Note: this method clones the passed array matrices before converting it into java.util.List and before checking the types of arrays. It is necessary to provide a guarantee that the elements of the returned list will not be changed to matrices of unallowed type.

Parameters:

arrayClass - the required class / interface of built-in arrays for all passed matrices.

matrices - an array of any matrices.

Returns:

the matrices argument (the same reference to a Java array).

Throws:

NullPointerException - if arrayClass or one of the passed matrices is null.

ClassCastException - if one of matrices contains built-in AlgART array that is not an instance of the type arrayClass (!arrayClass.isInstance(matrices[k].array())).

arraysOfParallelMatrices

public static <T extends Array> T[] arraysOfParallelMatrices(Class<T> arrayClass,
 List<? extends Matrix<?>> matrices)

Checks whether all passed matrices are not null and have equal dimensions and, if it is true, creates and returns Java array of built-in AlgART arrays of all passed matrices. In other words, in the returned array the element #k is matrices.get(k).array(). If some passed matrices are null or have different dimensions, throws a corresponding exception.

Parameters:

arrayClass - the required class / interface of built-in arrays for all passed matrices.

matrices - list of some matrices.

Returns:

array of built-in AlgART arrays of all passed matrices.

Throws:

NullPointerException - if arrayClass argument, the matrices list or one of its elements is null.

SizeMismatchException - if matrices.size()>1 and some of the passed matrices have different dimensions.

ClassCastException - if one of matrices contains built-in AlgART array that is not an instance of the type arrayClass (!arrayClass.isInstance(matrices[k].array())); it is impossible if you use generalized arguments.

arraysOfParallelMatrices

public static <T extends Array> T[] arraysOfParallelMatrices(Class<T> arrayClass,
 Collection<? extends Matrix<?>> matrices,
 boolean requireIdenticalType)

Equivalent of arraysOfParallelMatrices(Class, List) method, but, if requireIdenticalType=true, also checks that all passed matrices have identical element type.

Parameters:

arrayClass - the required class / interface of built-in arrays for all passed matrices.

matrices - list of some matrices.

Returns:

array of built-in AlgART arrays of all passed matrices.

Throws:

NullPointerException - if arrayClass argument, the matrices list or one of its elements is null.

SizeMismatchException - if matrices.size()>1 and some of the passed matrices have different dimensions.

IllegalArgumentException - if matrices.size()>1 and some of the passed matrices have different element type.

ClassCastException - if one of matrices contains built-in AlgART array that is not an instance of the type arrayClass (!arrayClass.isInstance(matrices[k].array())).

separate

public static void separate(ArrayContext context,
 List<? extends Matrix<? extends UpdatablePArray>> result,
 Matrix<? extends PArray> interleaved)

Analog of separate(ArrayContext, Matrix) method, that does not allocate memory, but stores the results into previously created list of matrices.

Note: if the source interleaved matrix has (n+1)-dimensions M₀xM₁x...xM_n, then the result list must contain M₀ elements, and each of them must be n-dimensional matrix M₁x...xM_n.

Parameters:

context - the context.

result - the list of the result matrices.

interleaved - the source interleaved matrix.

Throws:

NullPointerException - if interleaved argument, the results list or one of its elements is null.

SizeMismatchException - if some of the result matrices have dimensions, that do not match the last n dimensions M₁x...xM_n of (n+1)-dimensional source interleaved matrix.

IllegalArgumentException - if number of elements in the result list is not equal to the first interleaved dimension M₀, or if some of the result matrices have element type that is different from the element type of the source interleaved matrix.

IllegalStateException - if interleaved matrix is 1-dimensional.

separate

public static <T extends PArray> List<Matrix<T>> separate(ArrayContext context,
 Matrix<? extends T> interleaved)

Equivalent to separate(context, interleaved, Integer.MAX_VALUE) (no limitations).

Parameters:

context - the context.

interleaved - the source interleaved matrix.

Returns:

a list of matrices: "channels", interleaved in the source matrix along the first dimension.

Throws:

NullPointerException - if interleaved argument is null.

IllegalStateException - if interleaved matrix is 1-dimensional.

separate

public static <T extends PArray> List<Matrix<T>> separate(ArrayContext context,
 Matrix<? extends T> interleaved,
 int limit)

Splits a single (n+1)-dimensional interleaved matrix M₀xM₁x...xM_n along dimension #0 to M₀ separate n-dimensional matrices M₁x...xM_n and returns them as a list. The element with index (i₀,i₁,...,i_n) of the source matrix will be equal to the element with index (i₁,...,i_n) of the matrix list.get(i₀) in the returned list.

If the first dimension M₀=0, the returned list will be empty.

This method also checks, that the first dimension M₀=interleaved.dim(0) (which will be equal to the size of the returned list) is not greater than the passed limit and throws an exception if this limit is exceeded. Typically, this method is used for unpacking matrices where the first dimension cannot be too large — for example the number of color channels in RGBRGB... interleaving format — so it makes sense to limit this value, because too large first dimension (millions) usually means incorrect usage of this function. In any case, the number of returned matrices, greater than Integer.MAX_VALUE, usually leads to OutOfMemoryError.

Parameters:

context - the context; allows to specify (in particular) the memory model for creating returned matrices; may be null, then ArrayContext.DEFAULT_SINGLE_THREAD will be used.

interleaved - the source interleaved matrix.

limit - maximal allowed number of returned matrices (the first dimension of the source matrix).

Returns:

a list of matrices: "channels", interleaved in the source matrix along the first dimension (like the red, green, blue channels for 3-channel RGB image, stored in RGBRGB... format).

Throws:

NullPointerException - if interleaved argument is null.

IllegalStateException - if interleaved matrix is 1-dimensional.

IllegalArgumentException - if limit ≤ 0 or if the number of returned matrices >limit.

See Also:

• interleave(ArrayContext, List)
• asLayers(Matrix, int)

interleave

public static void interleave(ArrayContext context,
 Matrix<? extends UpdatablePArray> result,
 List<? extends Matrix<? extends PArray>> separated)

Analog of interleave(ArrayContext, List) method, that does not allocate memory, but stores the results into previously created result matrix.

Note: if the source separated matrices have n-dimensions M₁x...xM_n (remember that they must have identical element types and dimensions), then the result list must be (n+1)-dimensional matrix M₀xM₁x...xM_n, where M₀=separated.size().

The separated list must not be empty (M₀>0).

Parameters:

context - the context.

result - the result matrix.

separated - list of the source matrices; must be non-empty.

Throws:

NullPointerException - if result argument, the separated list or one of its elements is null.

SizeMismatchException - if some of the source matrices have dimensions, that do not match the last n dimensions M₁x...xM_n of (n+1)-dimensional result matrix.

IllegalArgumentException - if separated list is empty, or if number of elements in the separated list is not equal to the first result dimension M₀, or if some of the source matrices have element type that is different from the element type of the result matrix.

IllegalStateException - if result matrix is 1-dimensional.

interleave

public static <T extends PArray> Matrix<T> interleave(ArrayContext context,
 List<? extends Matrix<? extends T>> separated)

Merges (interleaves) K n-dimensional matrices with identical element types and dimensions M₁x...xM_n, passed in the separated list, into a single (n+1)-dimensional matrix KxM₁x...xM_n along the first dimension. The element with index (i₀,i₁,...,i_n) of the returned matrix will be equal to the element with index (i₁,...,i_n) of the matrix matrices.get(i₀).

The separated list must not be empty (K>0).

For example, if the source separated list contains 3 2-dimensional matrices, describing red, green and blue channels of RGB color image, then the result will be 3-dimensional matrix, where the lowest (first) dimension is 3 (for 3 channels) and the pixels are packed into the underlying array as a sequence RGBRGB...

Note: the matrix, returned by this method, is created by the call memoryModel.newMatrix(...), where memoryModel is context.getMemoryModel() or SimpleMemoryModel for null context. In the latter case (SimpleMemoryModel) this provides a guarantee, that the array in the returned matrix will be direct-accessible wrapper: Arrays.isJavaArrayWrapper(Array) will return true for the built-in array.

Parameters:

context - the context; allows to specify (in particular) the memory model for creating returned matrix; may be null, then ArrayContext.DEFAULT_SINGLE_THREAD will be used.

separated - list of the source matrices-"channels" (like the red, green, blue channels for 3-channel RGB image); must be non-empty.

Returns:

result matrix, where "channels" are interleaved along the first dimension (RGBRGB... sequence for 3-channel RGB image).

Throws:

NullPointerException - if separated list or one of its elements is null.

SizeMismatchException - if separated.size()>1 and some of the passed matrices have different dimensions.

IllegalArgumentException - if separated list is empty, or if separated.size()>1 and some of the passed matrices have different element type.

See Also:

• separate(ArrayContext, Matrix, int)
• mergeLayers(MemoryModel, List)

asLayers

public static <T extends Array> List<Matrix<T>> asLayers(Matrix<T> merged)

Equivalent to asLayers(merged, Integer.MAX_VALUE) (no limitations).

Parameters:

merged - the source merged matrix.

Returns:

a list of matrices: "layers" of the source one along the last dimension.

Throws:

NullPointerException - if merged argument is null.

IllegalStateException - if merged matrix is 1-dimensional.

asLayers

public static <T extends Array> List<Matrix<T>> asLayers(Matrix<T> merged,
 int limit)

Splits a single (n+1)-dimensional matrix M₀xM₁x...xM_n to M_n separate n-dimensional matrices M₀xM₁x...xM_n−1 and returns them as a list. The element with index (i₀,i₁,...,i_n) of the source matrix will be equal to the element with index (i₀,i₁,...,i_n−1) of the matrix list.get(i_n) in the returned list.

If the last dimension M_n=0, the returned list will be empty.

This method also checks, that the last dimension M_n=merged.dim(n) (that will be equal to the size of the returned list) is not greater than the passed limit and throws an exception if this limit is exceeded. Typically, this method is used for unpacking matrices where the last dimension cannot be too large — for example the number of color channels or the number of frames in a movie — so it makes sense to limit this value, because too large last dimension (millions) usually means incorrect usage of this function. In any case, the number of returned matrices, greater than Integer.MAX_VALUE, usually leads to OutOfMemoryError.

Note that the matrices in the returned list are views of the corresponding regions of the source matrix: modification in the source matrix will affect the returned matrices, and vice versa.

Parameters:

merged - the source merged matrix.

limit - maximal allowed number of returned matrices (the last dimension of the source matrix).

Returns:

a list of matrices: "layers" of the source one along the last dimension.

Throws:

NullPointerException - if merged argument is null.

IllegalStateException - if merged matrix is 1-dimensional.

IllegalArgumentException - if limit ≤ 0 or if the number of returned matrices >limit.

See Also:

• mergeLayers(MemoryModel, List)
• separate(ArrayContext, Matrix, int)

mergeLayers

public static <T extends Array> Matrix<T> mergeLayers(MemoryModel memoryModel,
 List<? extends Matrix<? extends T>> matrices)

Merges (concatenates) K n-dimensional matrices with identical element types and dimensions M₀xM₁x...xM_n−1, passed in the matrices list, into a single (n+1)-dimensional matrix M₀xM₁x...xM_n−1xK along the last dimension. The element with index (i₀,i₁,...,i_n) of the returned matrix will be equal to the element with index (i₀,i₁,...,i_n−1) of the matrix matrices.get(i_n).

The matrices list must not be empty (K>0).

For example, if the source list contains 3 2-dimensional matrices, describing red, green and blue channels of RGB color image, then the result will be 3-dimensional matrix, where the highest (new) dimension is 3 (for 3 channels) and the pixels are stored sequentially in "planes": RRR... (plane with z-index 0), then GGG... (plane with z-index 1), then BBB... (plane with z-index 2).

Parameters:

memoryModel - memory model for creating the result matrix.

matrices - list of the source matrices; must be non-empty.

Returns:

result merged matrix.

Throws:

NullPointerException - if arrayClass argument, the matrices list, one of its elements or memory model is null.

SizeMismatchException - if matrices.size()>1 and some of the passed matrices have different dimensions.

IllegalArgumentException - if matrices list is empty, or if matrices.size()>1 and some of the passed matrices have different element type.

See Also:

• asLayers(Matrix, int)
• interleave(ArrayContext, List)

checkDimensionEquality

public static void checkDimensionEquality(Collection<? extends Matrix<?>> matrices,
 boolean requireIdenticalType)

Checks the same condition as checkDimensionEquality(Collection) and, if requireIdenticalType=true, also checks that all passed matrices have identical element type.

Parameters:

matrices - list of some matrices.

Throws:

NullPointerException - if the matrices list or one of its elements is null.

SizeMismatchException - if matrices.size()>1 and some of the passed matrices have different dimensions.

IllegalArgumentException - if matrices.size()>1 and some of the passed matrices have different element type.

See Also:

• checkDimensionEquality(Matrix[])

checkDimensionEquality

public static void checkDimensionEquality(Collection<? extends Matrix<?>> matrices)

Checks whether all passed matrices are not null and have equal dimensions and, it is not so, throws a corresponding exception. The same check is performed by arraysOfParallelMatrices(java.lang.Class<T>, java.util.List<? extends net.algart.arrays.Matrix<?>>) method, but this method does not return any result.

Parameters:

matrices - list of some matrices.

Throws:

NullPointerException - if the matrices list or one of its elements is null.

SizeMismatchException - if matrices.size()>1 and some of the passed matrices have different dimensions.

See Also:

• checkDimensionEquality(Matrix[])

checkDimensionEquality

public static void checkDimensionEquality(Matrix<?>... matrices)

Checks whether all passed matrices are not null and have equal dimensions and, it is not so, throws a corresponding exception. Equivalent to checkDimensionEquality(Matrices.several(matrices)).

Parameters:

matrices - list of some matrices.

Throws:

NullPointerException - if the matrices list or one of its elements is null.

SizeMismatchException - if matrices.length>1 and some of the passed matrices have different dimensions.

asInterpolationFunc

public static Func asInterpolationFunc(Matrix<? extends PArray> matrix,
 Matrices.InterpolationMethod interpolationMethod,
 boolean checkRanges)

Returns a function of the coordinates represented by the given matrix with the given interpolation method. It means: if x₀, x₁, ..., x_n-1 (n=matrix.dimCount()) are integers inside the dimensions of the given matrix, then the returned function for such arguments returns

 f(x0, x1, ..., xn-1)=matrix.array().getDouble(matrix.index(x0, x1, ..., xn-1))
 

If the arguments of the returned function are not integer, the returned function uses the specified interpolation algorithm. Namely:

• If interpolationMethod is STEP_FUNCTION, the arguments are just truncated to integer indexes by Java operator (long)x. It is the simplest possible interpolation algorithm: the result is a step function.
• If interpolationMethod is POLYLINEAR_FUNCTION, the function value is calculated as a polylinear interpolation of 2^{matrix.dimCount()} neighbour matrix elements (linear interpolation in one-dimensional case, bilinear in 2-dimensional, etc.)

The real coordinates x_k must be inside the matrix:

 0 <= xk < matrix.dim(k)
 

In other case the behavior of the returned function depends on checkRanges argument. If it is true, IndexOutOfBoundsException is thrown while calling Func.get(double...) method, as while using Matrix.index(long...) method. If checkRanges is false, the results will be unspecified: maybe, some runtime exception will be thrown, maybe, Func.get(double...) method will return an incorrect value. Please use checkRanges=false if you are sure that the returned function will never be used outside the matrix: this mode can little increase the performance of algorithms that use the returned function.

For the case POLYLINEAR_FUNCTION, please note, that if the real coordinates x_k is near the high boundary, namely if matrix.dim(k)−1 <= x_k < matrix.dim(k), then interpolation will not be used, because necessary next matrix element is outside the matrix. Such real coordinate is processed as if it would be equal to matrix.dim(k)−1.

The number n of the arguments of Func.get(double...) method of the returned instance may be not equal to the number of matrix dimensions matrix.dimCount(). If n is less than matrix.dimCount(), the missing coordinates are supposed to be zero (0.0), i.e. ignored. If n is too big, all extra arguments x_k are ignored. In any case, the number of argument n must never be zero: the returned function throws IndexOutOfBoundsException when called without arguments.

Parameters:

matrix - the source AlgART matrix.

interpolationMethod - the algorithm of interpolation for non-integer arguments of the returned function.

checkRanges - whether the returned function must check all indexes to be inside the matrix.

Returns:

the view of the matrix as a mathematical function of matrix.dimCount() arguments.

Throws:

NullPointerException - if matrix or interpolationMethod argument is null.

See Also:

• asInterpolationFunc(Matrix, InterpolationMethod, double)
• isInterpolationFunc(Func)
• asResized(net.algart.arrays.Matrices.ResizingMethod, Matrix, long...)

asInterpolationFunc

public static Func asInterpolationFunc(Matrix<? extends PArray> matrix,
 Matrices.InterpolationMethod interpolationMethod,
 double outsideValue)

An analog of asInterpolationFunc(Matrix, InterpolationMethod, boolean) method, that use constant continuation for all coordinates outside the matrix. The returned function works almost like the result of asInterpolationFunc(matrix, interpolationMethod, true), but if the integer indexes are out of the required ranges, Func.get(double...) method returns the outsideValue instead throwing IndexOutOfBoundsException.

Parameters:

matrix - the source AlgART matrix.

interpolationMethod - the algorithm of interpolation for non-integer arguments of the returned function.

outsideValue - the value returned by Func.get(double...) method outside the matrix.

Returns:

the view of the matrix as a mathematical function of matrix.dimCount() arguments.

Throws:

NullPointerException - if matrix or interpolationMethod argument is null.

See Also:

• isInterpolationFunc(Func)

isInterpolationFunc

public static boolean isInterpolationFunc(Func f)

Returns true if the passed function is not null interpolation view of an AlgART matrix, created by this package. More precisely, if returns true if and only if the function is a result of one of the following methods:

• asInterpolationFunc(Matrix, InterpolationMethod, boolean),
• asInterpolationFunc(Matrix, InterpolationMethod, double).

You may get the underlying matrix, passed to those methods in the first argument, by getUnderlyingMatrix(Func).

Parameters:

f - some mathematical function (may be null, than the method returns false).

Returns:

whether this function is an interpolation view of some AlgART matrix.

See Also:

• getUnderlyingMatrix(Func)
• isOnlyInsideInterpolationFunc(Func)
• isCheckedOnlyInsideInterpolationFunc(Func)
• isContinuedInterpolationFunc(Func)

isOnlyInsideInterpolationFunc

public static boolean isOnlyInsideInterpolationFunc(Func f)

Returns true if the passed function is not null interpolation view of an AlgART matrix, created by asInterpolationFunc(Matrix, InterpolationMethod, boolean) method. You may get the underlying matrix, passed to those methods in the first argument, by getUnderlyingMatrix(Func).

Parameters:

f - some mathematical function (may be null, than the method returns false).

Returns:

whether this function is an interpolation view of some AlgART matrix without outside continuation.

See Also:

• isInterpolationFunc(Func)
• getUnderlyingMatrix(Func)

isCheckedOnlyInsideInterpolationFunc

public static boolean isCheckedOnlyInsideInterpolationFunc(Func f)

Returns true if the passed function is not null interpolation view of an AlgART matrix, created by asInterpolationFunc(Matrix, InterpolationMethod, boolean) method with true last argument. You may get the underlying matrix, passed to those methods in the first argument, by getUnderlyingMatrix(Func).

Parameters:

f - some mathematical function (may be null, than the method returns false).

Returns:

whether this function is an interpolation view of some AlgART matrix without outside continuation with checking indexes.

See Also:

• isInterpolationFunc(Func)
• getUnderlyingMatrix(Func)

isContinuedInterpolationFunc

public static boolean isContinuedInterpolationFunc(Func f)

Returns true if the passed function is not null interpolation view of an AlgART matrix, created by asInterpolationFunc(Matrix, InterpolationMethod, double) method. You may get the underlying matrix, passed to those methods in the first argument, by getUnderlyingMatrix(Func).

Parameters:

f - some mathematical function (may be null, than the method returns false).

Returns:

whether this function is an interpolation view of some AlgART matrix with outside continuation.

See Also:

• isInterpolationFunc(Func)
• getUnderlyingMatrix(Func)

getUnderlyingMatrix

public static Matrix<? extends PArray> getUnderlyingMatrix(Func f)

If the passed function is an interpolation view of an AlgART matrix, returns the reference to this matrix.

Parameters:

f - some interpolation view of an AlgART matrix.

Returns:

the reference to the AlgART matrix, represented by the passed view.

Throws:

NullPointerException - if f argument is null.

IllegalArgumentException - if !isInterpolationFunc(f)

See Also:

• isInterpolationFunc(Func)
• getInterpolationMethod(Func)

getOutsideValue

public static double getOutsideValue(Func f)

If the passed function is a continued interpolation view of an AlgART matrix, return the value used outside the matrix. In other words, this method returns the last argument of asInterpolationFunc(Matrix, InterpolationMethod, double) method, used for creating the passed view.

Parameters:

f - some continued interpolation view of an AlgART matrix.

Returns:

the value used outside the matrix.

Throws:

NullPointerException - if f argument is null.

IllegalArgumentException - if !isContinuedInterpolationFunc(f)

See Also:

• isInterpolationFunc(Func)
• getInterpolationMethod(Func)

getInterpolationMethod

public static Matrices.InterpolationMethod getInterpolationMethod(Func f)

If the passed function is an interpolation view of some AlgART matrix, returns the interpolation algorithm, used while creating this function. The result is equal to the second argument of methods asInterpolationFunc(Matrix, InterpolationMethod, boolean), asInterpolationFunc(Matrix, InterpolationMethod, double), used for creating the passed function.

Parameters:

f - some interpolation view of an AlgART matrix.

Returns:

the interpolation algorithm, used by this function.

Throws:

NullPointerException - if f argument is null.

IllegalArgumentException - if !isInterpolationFunc(f)

See Also:

• isInterpolationFunc(Func)

constantMatrix

public static <T extends PArray> Matrix<T> constantMatrix(double constant,
 Class<? extends T> requiredType,
 long... dim)

Returns a constant matrix, filled by the specified constant. Equivalent to asCoordFuncMatrix(true, ConstantFunc.getInstance(constant), requiredType, dim).

Parameters:

constant - the constant value of all elements of the returned matrix.

requiredType - desired type of the built-in array in the returned matrix.

dim - dimensions of the returned matrix.

Returns:

the matrix, defined by the passed function.

Throws:

NullPointerException - if requiredType argument is null.

IllegalArgumentException - in the same situations as asCoordFuncMatrix(boolean, Func, Class, long...) method.

asCoordFuncMatrix

public static <T extends PArray> Matrix<T> asCoordFuncMatrix(Func f,
 Class<? extends T> requiredType,
 long... dim)

Equivalent to asCoordFuncMatrix(true, f, requiredType, dim).

Parameters:

f - the mathematical function used for calculating all result matrix elements.

requiredType - desired type of the built-in array in the returned matrix.

dim - dimensions of the returned matrix.

Returns:

the matrix, defined by the passed function.

Throws:

NullPointerException - if f or requiredType argument is null.

IllegalArgumentException - in the same situations as asCoordFuncMatrix(boolean, Func, Class, long...) method.

asCoordFuncMatrix

public static <T extends PArray> Matrix<T> asCoordFuncMatrix(boolean truncateOverflows,
 Func f,
 Class<? extends T> requiredType,
 long... dim)

An analog of the asFuncMatrix(boolean, Func, Class, List) method, where the passed function is applied not to the elements of some source matrices, but to the indexes of the resulting matrix. More precisely, if result is the matrix returned by this method, then each its element

 result.array().getDouble(result.index(i0,i1,...,in-1))
 

is a result of the call f.get(i₀,i₁,...,i_n-1). So, this method does not require any source matrices.

Matrices, created by this method, are called functional matrices.

Please read comments to Arrays.asFuncArray(boolean, Func, Class, PArray...) about precise details of forming the elements of the returned matrix on the base of the real result of calling Func.get(double...) method.

Parameters:

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see comments to Arrays.asFuncArray(boolean, Func, Class, PArray...) method).

f - the mathematical function used for calculating all result matrix elements.

requiredType - desired type of the built-in array in the returned matrix.

dim - dimensions of the returned matrix.

Returns:

the matrix, defined by the passed function.

Throws:

NullPointerException - if f or requiredType argument is null.

IllegalArgumentException - if the number of dimensions is 0 (empty dim Java array), or if some of dimensions are negative, and also in the same situations as Arrays.asIndexFuncArray(boolean, Func, Class, long) method.

See Also:

• asResized(net.algart.arrays.Matrices.ResizingMethod, Matrix, long...)
• Arrays.isFuncArray(Array)
• Arrays.getFunc(Array)

isCoordFuncMatrix

public static boolean isCoordFuncMatrix(Matrix<? extends PArray> matrix)

Returns true if the passed matrix is not null functional matrix, created by this package, calculated on the base of coordinates only, not depending on another arrays/matrices. This method is equivalent to the following operator:

 matrix != null && Arrays.isIndexFuncArray(matrix.array())
 

Parameters:

matrix - the checked AlgART matrix (may be null, then the method returns false).

Returns:

true if the passed matrix a functional one, calculated on the base of coordinates only.

asFuncMatrix

public static <T extends PArray> Matrix<T> asFuncMatrix(Func f,
 Class<? extends T> requiredType,
 Matrix<? extends PArray> x)

Equivalent to asFuncMatrix(f, requiredType, several(PArray.class, x)).

Parameters:

f - the mathematical function applied to the passed AlgART matrix.

requiredType - desired type of the built-in array in the returned matrix.

x - the AlgART matrix.

Returns:

a view of the passed matrix, defined by the passed function.

Throws:

NullPointerException - if f, requiredType or the passed matrix is null.

IllegalArgumentException - in the same situations as asFuncMatrix(boolean, Func, Class, List) method.

asFuncMatrix

public static <T extends PArray> Matrix<T> asFuncMatrix(boolean truncateOverflows,
 Func f,
 Class<? extends T> requiredType,
 Matrix<? extends PArray> x)

Equivalent to asFuncMatrix(truncateOverflows, f, requiredType, several(PArray.class, x)).

Parameters:

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see comments to Arrays.asFuncArray(boolean, Func, Class, PArray...) method).

f - the mathematical function applied to the passed AlgART matrix.

requiredType - desired type of the built-in array in the returned matrix.

x - the AlgART matrix.

Returns:

a view of the passed matrix, defined by the passed function.

Throws:

NullPointerException - if f, requiredType or the passed matrix is null.

IllegalArgumentException - in the same situations as asFuncMatrix(boolean, Func, Class, List) method.

asFuncMatrix

public static <T extends PArray> Matrix<T> asFuncMatrix(Func f,
 Class<? extends T> requiredType,
 Matrix<? extends PArray> x1,
 Matrix<? extends PArray> x2)

Equivalent to asFuncMatrix(f, requiredType, several(PArray.class, x1, x2)).

Parameters:

f - the mathematical function applied to all passed AlgART matrices.

requiredType - desired type of the built-in array in the returned matrix.

x1 - 1st AlgART matrix.

x2 - 2nd AlgART matrix.

Returns:

a view of the passed matrices, defined by the passed function.

Throws:

NullPointerException - if f, requiredType or one of passed matrices is null.

IllegalArgumentException - in the same situations as asFuncMatrix(boolean, Func, Class, List) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

asFuncMatrix

public static <T extends PArray> Matrix<T> asFuncMatrix(boolean truncateOverflows,
 Func f,
 Class<? extends T> requiredType,
 Matrix<? extends PArray> x1,
 Matrix<? extends PArray> x2)

Equivalent to asFuncMatrix(truncateOverflows, f, requiredType, several(PArray.class, x1, x2)).

Parameters:

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see comments to Arrays.asFuncArray(boolean, Func, Class, PArray...) method).

f - the mathematical function applied to all passed AlgART matrices.

requiredType - desired type of the built-in array in the returned matrix.

x1 - 1st AlgART matrix.

x2 - 2nd AlgART matrix.

Returns:

a view of the passed matrices, defined by the passed function.

Throws:

NullPointerException - if f, requiredType or one of passed matrices is null.

IllegalArgumentException - in the same situations as asFuncMatrix(boolean, Func, Class, List) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

asFuncMatrix

public static <T extends PArray> Matrix<T> asFuncMatrix(Func f,
 Class<? extends T> requiredType,
 Matrix<? extends PArray> x1,
 Matrix<? extends PArray> x2,
 Matrix<? extends PArray> x3)

Equivalent to asFuncMatrix(f, requiredType, several(PArray.class, x1, x2, x3)).

Parameters:

f - the mathematical function applied to all passed AlgART matrices.

requiredType - desired type of the built-in array in the returned matrix.

x1 - 1st AlgART matrix.

x2 - 2nd AlgART matrix.

x3 - 3rd AlgART matrix.

Returns:

a view of the passed matrices, defined by the passed function.

Throws:

NullPointerException - if f, requiredType or one of passed matrices is null.

IllegalArgumentException - in the same situations as asFuncMatrix(boolean, Func, Class, List) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

asFuncMatrix

public static <T extends PArray> Matrix<T> asFuncMatrix(boolean truncateOverflows,
 Func f,
 Class<? extends T> requiredType,
 Matrix<? extends PArray> x1,
 Matrix<? extends PArray> x2,
 Matrix<? extends PArray> x3)

Equivalent to asFuncMatrix(truncateOverflows, f, requiredType, several(PArray.class, x1, x2, x3)).

Parameters:

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see comments to Arrays.asFuncArray(boolean, Func, Class, PArray...) method).

f - the mathematical function applied to all passed AlgART matrices.

requiredType - desired type of the built-in array in the returned matrix.

x1 - 1st AlgART matrix.

x2 - 2nd AlgART matrix.

x3 - 3rd AlgART matrix.

Returns:

a view of the passed matrices, defined by the passed function.

Throws:

NullPointerException - if f, requiredType or one of passed matrices is null.

IllegalArgumentException - in the same situations as asFuncMatrix(boolean, Func, Class, List) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

asFuncMatrix

public static <T extends PArray> Matrix<T> asFuncMatrix(Func f,
 Class<? extends T> requiredType,
 Matrix<? extends PArray> x1,
 Matrix<? extends PArray> x2,
 Matrix<? extends PArray> x3,
 Matrix<? extends PArray> x4)

Equivalent to asFuncMatrix(f, requiredType, several(PArray.class, x1, x2, x3, x4)).

Parameters:

f - the mathematical function applied to all passed AlgART matrices.

requiredType - desired type of the built-in array in the returned matrix.

x1 - 1st AlgART matrix.

x2 - 2nd AlgART matrix.

x3 - 3rd AlgART matrix.

x4 - 4th AlgART matrix.

Returns:

a view of the passed matrices, defined by the passed function.

Throws:

NullPointerException - if f, requiredType or one of passed matrices is null.

IllegalArgumentException - in the same situations as asFuncMatrix(boolean, Func, Class, List) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

asFuncMatrix

public static <T extends PArray> Matrix<T> asFuncMatrix(boolean truncateOverflows,
 Func f,
 Class<? extends T> requiredType,
 Matrix<? extends PArray> x1,
 Matrix<? extends PArray> x2,
 Matrix<? extends PArray> x3,
 Matrix<? extends PArray> x4)

Equivalent to asFuncMatrix(truncateOverflows, f, requiredType, several(PArray.class, x1, x2, x3, x4)).

Parameters:

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see comments to Arrays.asFuncArray(boolean, Func, Class, PArray...) method).

f - the mathematical function applied to all passed AlgART matrices.

requiredType - desired type of the built-in array in the returned matrix.

x1 - 1st AlgART matrix.

x2 - 2nd AlgART matrix.

x3 - 3rd AlgART matrix.

x4 - 4th AlgART matrix.

Returns:

a view of the passed matrices, defined by the passed function.

Throws:

NullPointerException - if f, requiredType or one of passed matrices is null.

IllegalArgumentException - in the same situations as asFuncMatrix(boolean, Func, Class, List) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

asFuncMatrix

public static <T extends PArray> Matrix<T> asFuncMatrix(Func f,
 Class<? extends T> requiredType,
 List<? extends Matrix<? extends PArray>> x)

Equivalent to asFuncMatrix(true, f, requiredType, x).

Parameters:

f - the mathematical function applied to all passed AlgART matrices.

requiredType - desired type of the built-in array in the returned matrix.

x - several AlgART matrices; must not be empty.

Returns:

a view of the passed x matrices, defined by the passed function.

Throws:

NullPointerException - if f, requiredType or x argument is null or if one of x elements is null.

IllegalArgumentException - in the same situations as asFuncMatrix(boolean, Func, Class, List).

SizeMismatchException - if x.size()>1 and some of the passed matrices have different dimensions.

asFuncMatrix

public static <T extends PArray> Matrix<T> asFuncMatrix(boolean truncateOverflows,
 Func f,
 Class<? extends T> requiredType,
 List<? extends Matrix<? extends PArray>> x)

An analog of Arrays.asFuncArray(boolean, Func, Class, PArray...) method for AlgART matrices. More precisely, this method is equivalent to m0.matrix(Arrays.asFuncArray(truncateOverflows, f, requiredType, arrays)), where m0 is x.get(0) and arrays is {x.get(0).array(), x.get(1).array(), ...}.

In addition, this method checks, whether all passed matrices have the same dimensions, and throws an exception in other case.

Parameters:

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see comments to Arrays.asFuncArray(boolean, Func, Class, PArray...) method).

f - the mathematical function applied to all passed AlgART matrices.

requiredType - desired type of the built-in array in the returned matrix.

x - several AlgART matrices; must not be empty.

Returns:

a view of the passed x matrices, defined by the passed function.

Throws:

NullPointerException - if f, requiredType or x argument is null or if one of x matrices is null.

IllegalArgumentException - if x.isEmpty() (no matrices passed), and also in the same situations as Arrays.asFuncArray(boolean, Func, Class, PArray...) method.

SizeMismatchException - if x.size()>1 and some of the passed matrices have different dimensions.

asUpdatableFuncMatrix

public static <T extends UpdatablePArray> Matrix<T> asUpdatableFuncMatrix(Func.Updatable f,
 Class<? extends T> requiredType,
 Matrix<? extends UpdatablePArray> x)

Equivalent to asUpdatableFuncMatrix(true, f, requiredType, x).

Parameters:

f - the mathematical function applied to the passed AlgART matrix.

requiredType - desired type of the built-in array in the returned matrix.

x - the source matrix.

Returns:

an updatable view of the passed x matrix, defined by the passed function.

Throws:

NullPointerException - if requiredType or x argument is null.

IllegalArgumentException - in the same situations as Arrays.asUpdatableFuncArray(boolean, net.algart.math.functions.Func.Updatable, Class, UpdatablePArray...) method.

asUpdatableFuncMatrix

public static <T extends UpdatablePArray> Matrix<T> asUpdatableFuncMatrix(boolean truncateOverflows,
 Func.Updatable f,
 Class<? extends T> requiredType,
 Matrix<? extends UpdatablePArray> x)

An analog of Arrays.asUpdatableFuncArray method for AlgART matrices. More precisely, this method is equivalent to x.matrix(Arrays.asUpdatableFuncArray(truncateOverflows, f, requiredType, x.array())).

Parameters:

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see comments to Arrays.asUpdatableFuncArray(boolean, net.algart.math.functions.Func.Updatable, Class, UpdatablePArray...) method).

f - the mathematical function applied to the passed AlgART matrix.

requiredType - desired type of the built-in array in the returned matrix.

x - the original AlgART matrix.

Returns:

an updatable view of the passed x matrix, defined by the passed function.

Throws:

NullPointerException - if requiredType or x argument is null.

IllegalArgumentException - in the same situations as Arrays.asUpdatableFuncArray(boolean, net.algart.math.functions.Func.Updatable, Class, UpdatablePArray...) method.

applyFunc

public static void applyFunc(ArrayContext context,
 Func f,
 Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> x)

Equivalent to applyFunc(context, true, f, result, x).

Parameters:

context - the context of copying; may be null, then it will be ignored.

f - the mathematical function applied to the source AlgART matrices.

result - the destination matrix.

x - the source matrix.

Throws:

NullPointerException - if f, result, x or one of x matrices is null.

IllegalArgumentException - in the same situations as Arrays.applyFunc(ArrayContext, boolean, Func, UpdatablePArray, PArray...) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

applyFunc

public static void applyFunc(ArrayContext context,
 boolean truncateOverflows,
 Func f,
 Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> x)

Equivalent to applyFunc(context, truncateOverflows, f, result, several(PArray.class, x)).

Parameters:

context - the context of copying; may be null, then it will be ignored.

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see comments to Arrays.asFuncArray(boolean, Func, Class, PArray...) method).

f - the mathematical function applied to the source AlgART matrices.

result - the destination matrix.

x - the AlgART matrix.

Throws:

NullPointerException - if f or one of passed matrices is null.

IllegalArgumentException - in the same situations as Arrays.applyFunc(ArrayContext, boolean, Func, UpdatablePArray, PArray...) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

applyFunc

public static void applyFunc(ArrayContext context,
 Func f,
 Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> x1,
 Matrix<? extends PArray> x2)

Equivalent to applyFunc(context, true, f, result, x1, x2).

Parameters:

context - the context of copying; may be null, then it will be ignored.

f - the mathematical function applied to the source AlgART matrices.

result - the destination matrix.

x1 - 1st AlgART matrix.

x2 - 2nd AlgART matrix.

Throws:

NullPointerException - if f, result, x or one of x matrices is null.

IllegalArgumentException - in the same situations as Arrays.applyFunc(ArrayContext, boolean, Func, UpdatablePArray, PArray...) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

applyFunc

public static void applyFunc(ArrayContext context,
 boolean truncateOverflows,
 Func f,
 Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> x1,
 Matrix<? extends PArray> x2)

Equivalent to applyFunc(context, truncateOverflows, f, result, several(PArray.class, x1, x2)).

Parameters:

context - the context of copying; may be null, then it will be ignored.

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see comments to Arrays.asFuncArray(boolean, Func, Class, PArray...) method).

f - the mathematical function applied to the source AlgART matrices.

result - the destination matrix.

x1 - 1st AlgART matrix.

x2 - 2nd AlgART matrix.

Throws:

NullPointerException - if f or one of passed matrices is null.

IllegalArgumentException - in the same situations as Arrays.applyFunc(ArrayContext, boolean, Func, UpdatablePArray, PArray...) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

applyFunc

public static void applyFunc(ArrayContext context,
 Func f,
 Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> x1,
 Matrix<? extends PArray> x2,
 Matrix<? extends PArray> x3)

Equivalent to applyFunc(context, true, f, result, x1, x2, x3).

Parameters:

context - the context of copying; may be null, then it will be ignored.

f - the mathematical function applied to the source AlgART matrices.

result - the destination matrix.

x1 - 1st AlgART matrix.

x2 - 2nd AlgART matrix.

x3 - 3rd AlgART matrix.

Throws:

NullPointerException - if f, result, x or one of x matrices is null.

IllegalArgumentException - in the same situations as Arrays.applyFunc(ArrayContext, boolean, Func, UpdatablePArray, PArray...) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

applyFunc

public static void applyFunc(ArrayContext context,
 boolean truncateOverflows,
 Func f,
 Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> x1,
 Matrix<? extends PArray> x2,
 Matrix<? extends PArray> x3)

Equivalent to applyFunc(context, truncateOverflows, f, result, several(PArray.class, x1, x2, x3)).

Parameters:

context - the context of copying; may be null, then it will be ignored.

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see comments to Arrays.asFuncArray(boolean, Func, Class, PArray...) method).

f - the mathematical function applied to the source AlgART matrices.

result - the destination matrix.

x1 - 1st AlgART matrix.

x2 - 2nd AlgART matrix.

x3 - 3rd AlgART matrix.

Throws:

NullPointerException - if f or one of passed matrices is null.

IllegalArgumentException - in the same situations as Arrays.applyFunc(ArrayContext, boolean, Func, UpdatablePArray, PArray...) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

applyFunc

public static void applyFunc(ArrayContext context,
 Func f,
 Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> x1,
 Matrix<? extends PArray> x2,
 Matrix<? extends PArray> x3,
 Matrix<? extends PArray> x4)

Equivalent to applyFunc(context, true, f, result, x1, x2, x3, x4).

Parameters:

context - the context of copying; may be null, then it will be ignored.

f - the mathematical function applied to the source AlgART matrices.

result - the destination matrix.

x1 - 1st AlgART matrix.

x2 - 2nd AlgART matrix.

x3 - 3rd AlgART matrix.

x4 - 4th AlgART matrix.

Throws:

NullPointerException - if f, result, x or one of x matrices is null.

IllegalArgumentException - in the same situations as Arrays.applyFunc(ArrayContext, boolean, Func, UpdatablePArray, PArray...) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

applyFunc

public static void applyFunc(ArrayContext context,
 boolean truncateOverflows,
 Func f,
 Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> x1,
 Matrix<? extends PArray> x2,
 Matrix<? extends PArray> x3,
 Matrix<? extends PArray> x4)

Equivalent to applyFunc(context, truncateOverflows, f, result, several(PArray.class, x1, x2, x3, x4)).

Parameters:

context - the context of copying; may be null, then it will be ignored.

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see comments to Arrays.asFuncArray(boolean, Func, Class, PArray...) method).

f - the mathematical function applied to the source AlgART matrices.

result - the destination matrix.

x1 - 1st AlgART matrix.

x2 - 2nd AlgART matrix.

x3 - 3rd AlgART matrix.

x4 - 4th AlgART matrix.

Throws:

NullPointerException - if f or one of passed matrices is null.

IllegalArgumentException - in the same situations as Arrays.applyFunc(ArrayContext, boolean, Func, UpdatablePArray, PArray...) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

applyFunc

public static void applyFunc(ArrayContext context,
 Func f,
 Matrix<? extends UpdatablePArray> result,
 List<? extends Matrix<? extends PArray>> x)

Equivalent to applyFunc(context, true, f, result, x).

Parameters:

context - the context of copying; may be null, then it will be ignored.

f - the mathematical function applied to the source AlgART matrices.

result - the destination matrix.

x - several AlgART matrices; may be empty.

Throws:

NullPointerException - if f, result, x or one of x matrices is null.

IllegalArgumentException - in the same situations as Arrays.applyFunc(ArrayContext, boolean, Func, UpdatablePArray, PArray...) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

applyFunc

public static void applyFunc(ArrayContext context,
 boolean truncateOverflows,
 Func f,
 Matrix<? extends UpdatablePArray> result,
 List<? extends Matrix<? extends PArray>> x)

Calls to Arrays.applyFunc(context, truncateOverflows, f, result.array(), arrays), where arrays is {x.get(0).array(), x.get(1).array(), ...}.

In addition, this method checks, whether all passed matrices have the same dimensions as result one, and throws an exception in other case.

Parameters:

context - the context of copying; may be null, then it will be ignored.

truncateOverflows - specifies behavior of typecasting to int, short, byte and char resulting values (see comments to Arrays.asFuncArray(boolean, Func, Class, PArray...) method).

f - the mathematical function applied to the source AlgART matrices.

result - the destination matrix.

x - several AlgART matrices; may be empty.

Throws:

NullPointerException - if f, result, x or one of x matrices is null.

IllegalArgumentException - in the same situations as Arrays.applyFunc(ArrayContext, boolean, Func, UpdatablePArray, PArray...) method.

SizeMismatchException - if some of the passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

applyPredicate

public static void applyPredicate(ArrayContext context,
 DoublePredicate predicate,
 Matrix<? extends UpdatableBitArray> result,
 Matrix<? extends PArray> source)

Performs the specified predicate for all elements of source to produce result.

Equivalent to applyFunc(context, func, result, source), where func has the following implementation:

  public double get(double... x) {
     return predicate.test(x[0]) ? 1.0 : 0.0;
  }
 

Parameters:

context - the context.

predicate - predicate to apply.

result - the result matrix.

source - the source matrix.

applyFunction

public static void applyFunction(ArrayContext context,
 DoubleUnaryOperator function,
 Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> source)

Performs the specified function for all elements of source to produce result.

Equivalent to applyFunc(context, func, result, source), where func has the following implementation:

  public double get(double... x) {
     return function.applyAsDouble(x[0]);
  }
 

Parameters:

context - the context.

function - function to apply.

result - the result matrix.

source - the source matrix.

asPrecision

public static Matrix<? extends PArray> asPrecision(Matrix<? extends PArray> matrix,
 Class<?> newElementType)

Returns an immutable view of the passed AlgART matrix, cast to another primitive element type (other precision) with automatic scaling, so that 0.0 is cast to 0.0 and maximal possible value of the source matrix is scaled to maximal possible value of the result. (For float and double elements we suppose that maximal possible value is 1.0.)

More precisely, if newElementType==matrix.elementType(), this function just returns the matrix argument without changes, in other case it is equivalent to the following operators:

     final Class newType = Arrays.type(PArray.class, newElementType);
     final Range destRange = Range.valueOf(0.0, Arrays.maxPossibleValue(newType));
     final Range srcRange = Range.valueOf(0.0, matrix.maxPossibleValue());
     return Matrices.asFuncMatrix(LinearFunc.getInstance(destRange, srcRange), newType, matrix);
 

Parameters:

matrix - the source AlgART matrix.

newElementType - required element type.

Returns:

the matrix with the required element type, where every element is equal to the corresponding element of the source matrix, multiplied by the automatically chosen scale.

Throws:

NullPointerException - if one of the arguments is null.

IllegalArgumentException - if the required element type is not a primitive type.

applyPrecision

public static void applyPrecision(ArrayContext context,
 Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> matrix)

Equivalent to creating a "lazy" matrix by lazy = asPrecision(matrix, result.elementType() call and copying it into the result argument by copy(context, result, lazy) call.

In addition, this method checks, whether all passed matrices have the same dimensions, and throws an exception in other case.

If the source and result matrices have the same element type, this method just copies matrix to result.

Parameters:

context - the context of copying; may be null, then it will be ignored.

result - the destination matrix.

matrix - the source matrix.

Throws:

NullPointerException - if result or matrix is null.

SizeMismatchException - if passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

asResized

public static Matrix<PArray> asResized(Matrices.ResizingMethod resizingMethod,
 Matrix<? extends PArray> matrix,
 long... newDim)

Returns an immutable view of the passed AlgART matrix, resized to the specified dimensions newDim. If is also a good example of cooperative using asInterpolationFunc, asCoordFuncMatrix and affine transforms of the functions: see below.

Namely, this method performs conversion of the matrix to a mathematical function from the coordinates (by asInterpolationFunc(Matrix, InterpolationMethod, double) method), transforms that function by the resizing linear operator (see LinearOperator.getDiagonalInstance(double...) method) and then performs the back conversion of the transformed function to the result matrix (by asCoordFuncMatrix(Func, Class, long...) method). The details depend on resizingMethod argument:

1. If resizingMethod is Matrices.ResizingMethod.SIMPLE, this method is equivalent to:

    Func interpolation = Matrices.asInterpolationFunc(
        matrix, Matrices.InterpolationMethod.STEP_FUNCTION, 0.0);
    Func transformed = LinearOperator.getDiagonalInstance(diagonal).apply(interpolation);
    Matrix result = Matrices.asCoordFuncMatrix(
        transformed, matrix.type(PArray.class), newDim);
    

   Here diagonal is the array of relations between old and new dimensions:

        diagonal[k] = (double)matrix.dim(k) / (double)newDim[k]
    

   It is the simplest possible resizing method without any interpolation or averaging: every element of the returned matrix is strictly equal to some element of the source one.
   
2. If resizingMethod is Matrices.ResizingMethod.AVERAGING, this method does the same, but if some of diagonal values are greater than 1.5 (that means compression), it also performs additional transformation of transformed function by the operator ApertureFilterOperator.getAveragingInstance(long...apertureDim), where apertureDim is the sizes of the aperture in the source matrix, mapped to a single result element. As a result, the value of each result element is an average from several source elements, that are mapped to that one by this compression. The details of this averaging are not specified. This method is necessary while compression, if you want to get maximally "good" result picture. It works fine while compression in the integer number of times (all diagonal values are integers). In other case, Matrices.ResizingMethod.POLYLINEAR_AVERAGING mode can produce better results.
   
3. If resizingMethod is Matrices.ResizingMethod.POLYLINEAR_INTERPOLATION or Matrices.ResizingMethod.POLYLINEAR_AVERAGING, this method does the same as in cases 1 and 2, but the argument of asInterpolationFunc is POLYLINEAR_FUNCTION instead of STEP_FUNCTION. These modes are useful while expanding the matrix, because allow to use interpolation for values "between" its elements. The Matrices.ResizingMethod.POLYLINEAR_AVERAGING is usually the best choice.
   
4. If resizingMethod is some inheritor of Matrices.ResizingMethod.Averaging class, this method does the same as in cases Matrices.ResizingMethod.AVERAGING and Matrices.ResizingMethod.POLYLINEAR_AVERAGING, but the averaging operator will be created not by ApertureFilterOperator.getAveragingInstance(long...apertureDim), but by ApertureFilterOperator.getInstance(Func func, long...apertureDim) method, where the first argument is the result of resizingMethod.getAveragingFunc(apertureDim). It allows to specify non-standard averaging algorithm. For example, for binary matrices, containing a little number of unit elements, Func.MAX can be a better choice than the usual linear averaging.

There is an exception from the rules listed above. If the source matrix is empty (at least one dimension is 0), the returned matrix will be zero-filled always. (In this case, there are no ways to calculate any elements.)

Parameters:

resizingMethod - the algorithm of resizing.

matrix - the source AlgART matrix.

newDim - the dimensions of resized matrix.

Returns:

the resized matrix.

Throws:

NullPointerException - if resizingMethod, matrix or newDim argument is null.

IllegalArgumentException - if the number of newDim elements is not equal to matrix.dimCount(), or if some of new dimensions are negative.

See Also:

• resize(ArrayContext, Matrices.ResizingMethod, Matrix, Matrix)
• asResized(Matrices.ResizingMethod, Matrix, long[], double[])

asResized

public static Matrix<PArray> asResized(Matrices.ResizingMethod resizingMethod,
 Matrix<? extends PArray> matrix,
 long[] newDim,
 double[] scales)

An extended analog of asResized(Matrices.ResizingMethod, Matrix, long...) method, allowing to precisely specify a custom scaling value along every coordinate. Namely, while that method scales every coordinate #k in newDim[k]/matrix.dim(k) times, this method scales it precisely in scales[k] time. If, for every k, we have

     scales[k]==(double)newDim[k]/(double)matrix.dim(k)
 

or if scales argument is null, this method is equivalent to asResized(Matrices.ResizingMethod, Matrix, long...).

To get a strict specification of behaviour of this method, please look at the comments to asResized(Matrices.ResizingMethod, Matrix, long...), section 1, and replace definition of diagonal array with the following:

     diagonal[k] = scales == null ? (double)matrix.dim(k) / (double)newDim[k] : 1.0 / scales[k]
 

Parameters:

resizingMethod - the algorithm of resizing.

matrix - the source AlgART matrix.

newDim - the dimensions of resized matrix.

scales - the scales of resizing along every coordinate; may be null, then calculated automatically as scales[k] = (double)newDim[k]/(double)matrix.dim(k).

Returns:

the resized matrix.

Throws:

NullPointerException - if resizingMethod, matrix or newDim argument is null.

IllegalArgumentException - if the length of newDim or (when scales!=null) scales array is not equal to matrix.dimCount(), or if some of new dimensions are negative.

See Also:

• resize(ArrayContext, Matrices.ResizingMethod, Matrix, Matrix)

resize

public static void resize(ArrayContext context,
 Matrices.ResizingMethod resizingMethod,
 Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> src)

Resizes the source matrix to the dimensions of the passed result matrix and stores the resized matrix in result argument.

This method is equivalent to the following operators:

     Matrix<?> lazy = Matrices.asResized(resizingMethod, src, result.dimensions());
     Matrices.copy(context, result, lazy, 0, false);
 

Note: in many cases this method works essentially faster than simple reading all elements of the result of asResized method.

Please draw attention to the argument strictMode=false of Matrices.copy method: it is important for providing good performance for resizing large matrices. This argument specifies, that the precise results of this method may little differ from the elements of the asResized result (the "lazy" matrix above).

Moreover, the precise results of this method may little differ also from the results of the code above (calling Matrices.copy method).

Usually the differences are little numeric errors, connected with limited precision of floating-point calculations of the coordinates. For example, it is possible that the coordinates of the set of points, the values of which are averaged in Matrices.ResizingMethod.AVERAGING resizing method, will be slightly different in this method and in the precise specification of asResized(net.algart.arrays.Matrices.ResizingMethod, Matrix, long...) (according usage of ApertureFilterOperator.getAveragingInstance(long...apertureDim) operator). For Matrices.ResizingMethod.AVERAGING mode it may lead to rounding coordinates to another integers, so, the result of averaging will be little other. For more accurate Matrices.ResizingMethod.POLYLINEAR_AVERAGING) mode the result of averaging will be almost the same.

By the way, in a case of such differences the results of this method usually better correspond to intuitive expectations of the results of resizing.

Parameters:

context - the context of resizing; may be null, then it will be ignored.

resizingMethod - the algorithm of resizing.

result - the destination matrix.

src - the source matrix.

add

public static void add(Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> other)

Addition: equivalent to addToOther(result, result, other).

Parameters:

result - matrix a, will be replaced with elementwise sum a + b.

other - matrix b.

addToOther

public static void addToOther(Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> a,
 Matrix<? extends PArray> b)

Addition: equivalent to applyFunc(ArrayContext.DEFAULT_SINGLE_THREAD, Func.X_PLUS_Y, result, a, b).

Parameters:

result - elementwise sum a + b.

a - matrix a.

b - matrix b.

subtract

public static void subtract(Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> other)

Subtraction: equivalent to subtractToOther(result, result, other).

Parameters:

result - matrix a, will be replaced with elementwise difference a − b.

other - matrix b.

subtractToOther

public static void subtractToOther(Matrix<? extends UpdatablePArray> result,
 Matrix<? extends PArray> a,
 Matrix<? extends PArray> b)

Subtraction: equivalent to applyFunc(ArrayContext.DEFAULT_SINGLE_THREAD, Func.X_MINUS_Y, result, a, b).

Parameters:

result - elementwise difference a − b.

a - matrix a.

b - matrix b.

bitOr

public static void bitOr(Matrix<? extends UpdatableBitArray> result,
 Matrix<? extends BitArray> other)

Binary OR: equivalent to bitOrToOther(result, result, other).

Parameters:

result - matrix a, will be replaced with binary OR a | b.

other - matrix b.

bitOrToOther

public static void bitOrToOther(Matrix<? extends UpdatableBitArray> result,
 Matrix<? extends BitArray> a,
 Matrix<? extends BitArray> b)

Binary OR: equivalent to applyFunc(ArrayContext.DEFAULT_SINGLE_THREAD, Func.MAX, result, a, b).

Parameters:

result - binary OR a | b.

a - matrix a.

b - matrix b.

bitAnd

public static void bitAnd(Matrix<? extends UpdatableBitArray> result,
 Matrix<? extends BitArray> other)

Binary AND: equivalent to bitAndToOther(result, result, other).

Parameters:

result - matrix a, will be replaced with binary AND a & b.

other - matrix b.

bitAndToOther

public static void bitAndToOther(Matrix<? extends UpdatableBitArray> result,
 Matrix<? extends BitArray> a,
 Matrix<? extends BitArray> b)

Binary AND: equivalent to applyFunc(ArrayContext.DEFAULT_SINGLE_THREAD, Func.MIN, result, a, b).

Parameters:

result - binary AND a | b.

a - matrix a.

b - matrix b.

bitXor

public static void bitXor(Matrix<? extends UpdatableBitArray> result,
 Matrix<? extends BitArray> other)

Binary XOR: equivalent to bitXorToOther(result, result, other).

Parameters:

result - matrix a, will be replaced with binary XOR a ^ b.

other - matrix b.

bitXorToOther

public static void bitXorToOther(Matrix<? extends UpdatableBitArray> result,
 Matrix<? extends BitArray> a,
 Matrix<? extends BitArray> b)

Binary XOR: equivalent to applyFunc(ArrayContext.DEFAULT_SINGLE_THREAD, Func.ABS_DIFF, result, a, b).

Parameters:

result - binary XOR a ^ b.

a - matrix a.

b - matrix b.

bitDiff

public static void bitDiff(Matrix<? extends UpdatableBitArray> result,
 Matrix<? extends BitArray> other)

Binary AND-NOT: equivalent to bitDiffToOther(result, result, other).

Parameters:

result - matrix a, will be replaced with binary AND-NOT a & ~b.

other - matrix b.

bitDiffToOther

public static void bitDiffToOther(Matrix<? extends UpdatableBitArray> result,
 Matrix<? extends BitArray> a,
 Matrix<? extends BitArray> b)

Binary AND-NOT: equivalent to applyFunc(ArrayContext.DEFAULT_SINGLE_THREAD, Func.POSITIVE_DIFF, result, a, b).

Parameters:

result - binary AND-NOT a & ~b.

a - matrix a.

b - matrix b.

bitNot

public static void bitNot(Matrix<? extends UpdatableBitArray> bitMatrix)

Binary NOT: equivalent to bitNotToOther(bitMatrix, bitMatrix).

Parameters:

bitMatrix - matrix a, will be replaced with binary NOT ~a.

bitNotToOther

public static void bitNotToOther(Matrix<? extends UpdatableBitArray> result,
 Matrix<? extends BitArray> source)

Binary NOT: equivalent to applyFunc(ArrayContext.DEFAULT_SINGLE_THREAD, Func.REVERSE, result, source).

Parameters:

result - binary NOT ~a.

source - matrix a.

packBitsGreater

public static void packBitsGreater(Matrix<? extends UpdatableBitArray> result,
 Matrix<? extends PArray> intensities,
 double threshold)

Equivalent to packBitsGreater(result.array(), intensities.array(), threshold)

Parameters:

result - result bit matrix.

intensities - source matrix.

threshold - threshold that will be compared with all elements of intensities.

Throws:

NullPointerException - if one of the passed matrices is null.

SizeMismatchException - if the passed matrices have different dimensions.

packBitsLess

public static void packBitsLess(Matrix<? extends UpdatableBitArray> result,
 Matrix<? extends PArray> intensities,
 double threshold)

Equivalent to packBitsLess(result.array(), intensities.array(), threshold)

Parameters:

result - result bit matrix.

intensities - source matrix.

threshold - threshold that will be compared with all elements of intensities.

Throws:

NullPointerException - if one of the passed matrices is null.

SizeMismatchException - if the passed matrices have different dimensions.

packBitsGreaterOrEqual

public static void packBitsGreaterOrEqual(Matrix<? extends UpdatableBitArray> result,
 Matrix<? extends PArray> intensities,
 double threshold)

Equivalent to packBitsGreaterOrEqual(result.array(), intensities.array(), threshold)

Parameters:

result - result bit matrix.

intensities - source matrix.

threshold - threshold that will be compared with all elements of intensities.

Throws:

NullPointerException - if one of the passed matrices is null.

SizeMismatchException - if the passed matrices have different dimensions.

packBitsLessOrEqual

public static void packBitsLessOrEqual(Matrix<? extends UpdatableBitArray> result,
 Matrix<? extends PArray> intensities,
 double threshold)

Equivalent to packBitsLessOrEqual(result.array(), intensities.array(), threshold)

Parameters:

result - result bit matrix.

intensities - source matrix.

threshold - threshold that will be compared with all elements of intensities.

Throws:

NullPointerException - if one of the passed matrices is null.

SizeMismatchException - if the passed matrices have different dimensions.

unpackBits

public static void unpackBits(Matrix<? extends UpdatablePArray> result,
 Matrix<? extends BitArray> bits,
 double filler0,
 double filler1)

Equivalent to unpackBits(result.array(), bits.array(), filler0, filler1)

Parameters:

result - result matrix.

bits - source bit matrix.

filler0 - the value that will be set in result for zero bits.

filler1 - the value that will be set in result for unit bits.

Throws:

NullPointerException - if one of the passed matrices is null.

SizeMismatchException - if the passed matrices have different dimensions.

unpackUnitBits

public static void unpackUnitBits(Matrix<? extends UpdatablePArray> result,
 Matrix<? extends BitArray> bits,
 double filler1)

Equivalent to unpackUnitBits(result.array(), bits.array(), filler1)

Parameters:

result - result matrix.

bits - source bit matrix.

filler1 - the value that will be set in result for unit bits.

Throws:

NullPointerException - if one of the passed matrices is null.

SizeMismatchException - if the passed matrices have different dimensions.

unpackZeroBits

public static void unpackZeroBits(Matrix<? extends UpdatablePArray> result,
 Matrix<? extends BitArray> bits,
 double filler0)

Equivalent to unpackZeroBits(result.array(), bits.array(), filler0)

Parameters:

result - result matrix.

bits - source bit matrix.

filler0 - the value that will be set in result for zero bits.

Throws:

NullPointerException - if one of the passed matrices is null.

SizeMismatchException - if the passed matrices have different dimensions.

asShifted

public static Matrix<Array> asShifted(Matrix<? extends Array> matrix,
 long... shifts)

Returns an immutable view of the passed AlgART matrix, pseudo-cyclically shifted to the right for every coordinate.

The shift is not really cyclic. Really, the built-in AlgART is cyclically shifted to the right, that means shifting end elements of every line #y to the beginning of the next line #y+1, end lines of every plane (layer) #z to the beginning of the next plane #z+1, etc. More precisely, this method is equivalent to the following operators:

 Array array = matrix.array();
 Array shifted = Arrays.asShifted(array, shift);
 Matrix<Array> result = matrix.matrix(shifted);
 

where the shift of the built-in array is calculated as

 shifts[0] +
 + shifts[1] * matrix.dim(0) +
 + shifts[2] * matrix.dim(0) * matrix.dim(1) +
 + . . . +
 + shifts[n-1] * matrix.dim(0) * matrix.dim(1) * ... * matrix.dim(n-2) (n = shifts.length)
 

All calculations are performed with long type without any overflow checks. All elements of shifts array are always used, regardless of the number of matrix dimensions. (You can note that extra elements of shifts array are ignored in fact: they add k*length summand, where k is an integer and length is the array length.) If shifts array is empty, the resulting shift=0.

The result of this method has Matrix<Array> generic type always, though the built-in array of the returned matrix implements the more specific interface BitArray, CharArray, ByteArray, ShortArray, IntArray, LongArray, FloatArray, DoubleArray or ObjectArray (the same as the built-in array of the passed matrix). If you need to get the matrix with more specific generic type, please use Matrix.cast(Class) method. For example:

 Matrix<PFixedArray> src = ...; // source matrix
 Matrix<PFixedArray> dest = Matrices.asShifted(src, dx, dy).cast(PFixedArray.class);
 

Parameters:

matrix - the source AlgART matrix.

shifts - the shifts (to the right) of all indexes in the returned view.

Returns:

a shifted view of the passed matrix.

Throws:

NullPointerException - if shifts or matrix argument is null.

toByteJavaArray

public static byte[] toByteJavaArray(Matrix<? extends PArray> matrix)

Equivalent to Arrays.toByteJavaArray(matrix.array()).

Parameters:

matrix - the source AlgART matrix.

Returns:

Java array containing all the elements in this matrix, cast to byte type.

Throws:

NullPointerException - if matrix argument is null.

TooLargeArrayException - if the matrix size is greater than Integer.MAX_VALUE.

See Also:

• Array.ja()

toByteJavaArray

public static byte[] toByteJavaArray(byte[] result,
 Matrix<? extends PArray> matrix)

Equivalent to Arrays.toByteJavaArray(result, matrix.array()).

Parameters:

matrix - the source AlgART matrix.

Returns:

a reference to result argument or (when result==null) a newly created array: Java array containing all the elements in the source matrix, cast to byte type according to AlgART rules.

Throws:

NullPointerException - if matrix argument is null.

TooLargeArrayException - if the matrix size is greater than Integer.MAX_VALUE.

IndexOutOfBoundsException - if the result argument is not null, but its length is too small: less than matrix.size().

See Also:

• Array.ja()

toShortJavaArray

public static short[] toShortJavaArray(Matrix<? extends PArray> matrix)

Equivalent to Arrays.toShortJavaArray(matrix.array()).

Parameters:

matrix - the source AlgART matrix.

Returns:

Java array containing all the elements in this matrix, cast to short type.

Throws:

NullPointerException - if matrix argument is null.

TooLargeArrayException - if the matrix size is greater than Integer.MAX_VALUE.

See Also:

• Array.ja()

toShortJavaArray

public static short[] toShortJavaArray(short[] result,
 Matrix<? extends PArray> matrix)

Equivalent to Arrays.toShortJavaArray(result, matrix.array()).

Parameters:

matrix - the source AlgART matrix.

Returns:

a reference to result argument or (when result==null) a newly created array: Java array containing all the elements in the source matrix, cast to short type according to AlgART rules.

Throws:

NullPointerException - if matrix argument is null.

TooLargeArrayException - if the matrix size is greater than Integer.MAX_VALUE.

IndexOutOfBoundsException - if the result argument is not null, but its length is too small: less than matrix.size().

See Also:

• Array.ja()

toIntJavaArray

public static int[] toIntJavaArray(Matrix<? extends PArray> matrix)

Equivalent to Arrays.toIntJavaArray(matrix.array()).

Parameters:

matrix - the source AlgART matrix.

Returns:

Java array containing all the elements in this matrix, cast to int type.

Throws:

NullPointerException - if matrix argument is null.

TooLargeArrayException - if the matrix size is greater than Integer.MAX_VALUE.

See Also:

• Array.ja()

toIntJavaArray

public static int[] toIntJavaArray(int[] result,
 Matrix<? extends PArray> matrix)

Equivalent to Arrays.toIntJavaArray(result, matrix.array()).

Parameters:

matrix - the source AlgART matrix.

Returns:

a reference to result argument or (when result==null) a newly created array: Java array containing all the elements in the source matrix, cast to int type according to AlgART rules.

Throws:

NullPointerException - if matrix argument is null.

TooLargeArrayException - if the matrix size is greater than Integer.MAX_VALUE.

IndexOutOfBoundsException - if the result argument is not null, but its length is too small: less than matrix.size().

See Also:

• Array.ja()

toLongJavaArray

public static long[] toLongJavaArray(Matrix<? extends PArray> matrix)

Equivalent to Arrays.toLongJavaArray(matrix.array()).

Parameters:

matrix - the source AlgART matrix.

Returns:

Java array containing all the elements in this matrix, cast to long type.

Throws:

NullPointerException - if matrix argument is null.

TooLargeArrayException - if the matrix size is greater than Integer.MAX_VALUE.

See Also:

• Array.ja()

toLongJavaArray

public static long[] toLongJavaArray(long[] result,
 Matrix<? extends PArray> matrix)

Equivalent to Arrays.toLongJavaArray(result, matrix.array()).

Parameters:

matrix - the source AlgART matrix.

Returns:

a reference to result argument or (when result==null) a newly created array: Java array containing all the elements in the source matrix, cast to long type according to AlgART rules.

Throws:

NullPointerException - if matrix argument is null.

TooLargeArrayException - if the matrix size is greater than Integer.MAX_VALUE.

IndexOutOfBoundsException - if the result argument is not null, but its length is too small: less than matrix.size().

See Also:

• Array.ja()

toFloatJavaArray

public static float[] toFloatJavaArray(Matrix<? extends PArray> matrix)

Equivalent to Arrays.toFloatJavaArray(matrix.array()).

Parameters:

matrix - the source AlgART matrix.

Returns:

Java array containing all the elements in this matrix, cast to float type.

Throws:

NullPointerException - if matrix argument is null.

TooLargeArrayException - if the matrix size is greater than Integer.MAX_VALUE.

See Also:

• Array.ja()

toFloatJavaArray

public static float[] toFloatJavaArray(float[] result,
 Matrix<? extends PArray> matrix)

Equivalent to Arrays.toFloatJavaArray(result, matrix.array()).

Parameters:

matrix - the source AlgART matrix.

Returns:

a reference to result argument or (when result==null) a newly created array: Java array containing all the elements in the source matrix, cast to float type according to AlgART rules.

Throws:

NullPointerException - if matrix argument is null.

TooLargeArrayException - if the matrix size is greater than Integer.MAX_VALUE.

IndexOutOfBoundsException - if the result argument is not null, but its length is too small: less than matrix.size().

See Also:

• Array.ja()

toDoubleJavaArray

public static double[] toDoubleJavaArray(Matrix<? extends PArray> matrix)

Equivalent to Arrays.toDoubleJavaArray(matrix.array()).

Parameters:

matrix - the source AlgART matrix.

Returns:

Java array containing all the elements in this matrix, cast to double type.

Throws:

NullPointerException - if matrix argument is null.

TooLargeArrayException - if the matrix size is greater than Integer.MAX_VALUE.

See Also:

• Array.ja()

toDoubleJavaArray

public static double[] toDoubleJavaArray(double[] result,
 Matrix<? extends PArray> matrix)

Equivalent to Arrays.toDoubleJavaArray(result, matrix.array()).

Parameters:

matrix - the source AlgART matrix.

Returns:

a reference to result argument or (when result==null) a newly created array: Java array containing all the elements in the source matrix, cast to double type according to AlgART rules.

Throws:

NullPointerException - if matrix argument is null.

TooLargeArrayException - if the matrix size is greater than Integer.MAX_VALUE.

IndexOutOfBoundsException - if the result argument is not null, but its length is too small: less than matrix.size().

See Also:

• Array.ja()

clone

public static Matrix<? extends UpdatablePArray> clone(Matrix<? extends PArray> matrix)

Equivalent to clone(matrix, Arrays.SMM).

Note: this operation can optimize access to this matrix in many times, if it is lazy-calculated and not too large (can be placed in available Java memory). It performs cloning with maximal speed via multithreading optimization. We recommend to call it after lazy calculations.

Returns:

exact updatable clone of the passed matrix.

Throws:

NullPointerException - if the argument is null.

clone

public static Matrix<? extends UpdatablePArray> clone(MemoryModel memoryModel,
 Matrix<? extends PArray> matrix)

Returns an exact updatable clone of the given matrix, created in the given memory model. Equivalent to the following operators:

     final Matrix result = memoryModel.newMatrix(UpdatablePArray.class, matrix);
     Matrices.copy(null, result, matrix); // - maximally fast multithreading copying
     (return result)
 

Returns:

exact updatable clone of the passed matrix.

Throws:

NullPointerException - if one of the arguments is null.

copy

public static Arrays.CopyStatus copy(ArrayContext context,
 Matrix<? extends UpdatableArray> dest,
 Matrix<? extends Array> src)

This method just calls Arrays.copy(context, dest.array(), src.array()), if the passed matrices have the same dimensions, or throws SizeMismatchException in other case.

Parameters:

context - the context of copying; may be null, then it will be ignored.

dest - the destination matrix.

src - the source matrix.

Returns:

the information about copying.

Throws:

NullPointerException - if src or dest argument is null.

IllegalArgumentException - if the source and destination element types do not match.

SizeMismatchException - if the passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

copy

public static Arrays.CopyStatus copy(ArrayContext context,
 Matrix<? extends UpdatableArray> dest,
 Matrix<? extends Array> src,
 int numberOfTasks)

This method just calls Arrays.copy(context, dest.array(), src.array(), numberOfTasks), if the passed matrices have the same dimensions, or throws SizeMismatchException in other case.

Parameters:

context - the context of copying; may be null, then it will be ignored.

dest - the destination matrix.

src - the source matrix.

numberOfTasks - the required number of parallel tasks; may be 0, then it will be chosen automatically.

Returns:

the information about copying.

Throws:

NullPointerException - if src or dest argument is null.

IllegalArgumentException - if the source and destination element types do not match, or if the numberOfThreads argument is negative.

SizeMismatchException - if the passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

copy

public static Arrays.CopyStatus copy(ArrayContext context,
 Matrix<? extends UpdatableArray> dest,
 Matrix<? extends Array> src,
 int numberOfTasks,
 boolean strictMode)

This method just calls Arrays.copy(context, dest.array(), src.array(), numberOfTasks, strictMode), if the passed matrices have the same dimensions, or throws SizeMismatchException in other case.

Parameters:

context - the context of copying; may be null, then it will be ignored.

dest - the destination matrix.

src - the source matrix.

numberOfTasks - the required number of parallel tasks; may be 0, then it will be chosen automatically.

strictMode - if false, optimization is allowed even if it can lead to little differences between the source and copied elements.

Returns:

the information about copying.

Throws:

NullPointerException - if src or dest argument is null.

IllegalArgumentException - if the source and destination element types do not match, or if the numberOfThreads argument is negative.

SizeMismatchException - if the passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

compareAndCopy

public static Arrays.ComparingCopyStatus compareAndCopy(ArrayContext context,
 Matrix<? extends UpdatableArray> dest,
 Matrix<? extends Array> src)

This method just calls Arrays.compareAndCopy(context, dest.array(), src.array()), if the passed matrices have the same dimensions, or throws SizeMismatchException in other case.

Parameters:

context - the context of copying; may be null, then it will be ignored.

dest - the destination matrix.

src - the source matrix.

Returns:

the result of Arrays.compareAndCopy call.

Throws:

NullPointerException - if src or dest argument is null.

IllegalArgumentException - if the source and destination element types do not match.

SizeMismatchException - if the passed matrices have different dimensions.

IOError - if the current thread is interrupted by the standard Thread.interrupt() call.

copy

public static void copy(Matrix<? extends UpdatablePArray> dest,
 Matrix<? extends PArray> src)

Just copies src into dest without using multithreading. Equivalent to copy(ArrayContext.DEFAULT_SINGLE_THREAD, dest, src).

Parameters:

dest - the destination matrix.

src - the src matrix.

Throws:

NullPointerException - if src or dest argument is null.

IllegalArgumentException - if the src and destination element types do not match.

SizeMismatchException - if the passed matrices have different dimensions.

copyRegion

public static void copyRegion(ArrayContext context,
 Matrix<? extends UpdatableArray> dest,
 Matrix<? extends Array> src,
 Matrices.Region destRegion,
 long... shifts)

Copies the specified region from src AlgART matrix to dest AlgART matrix. The region in dest matrix, that will be copied from src, is specified by destRegion argument. The corresponding region in src matrix, that will be copied into dest, is obtained from destRegion by subtracting the specified shifts from all coordinates of destRegion.

More precisely, this method is equivalent to the following loop (and, of course, works faster):

 for (all possible long coordinates x0, x1, ..., xn-1
     in ranges destRegion.coordRange(0), destRegion.coordRange(1),
     ..., destRegion.coordRange(n-1))
 {
     if (destRegion.contains(x0, x1, ..., xn-1) {
         long x'0 = x0 - (shifts.length > 0 ? shifts[0] : 0);
         long x'1 = x1 - (shifts.length > 1 ? shifts[1] : 0);
         ...
         long x'n-1 = xn-1 - (shifts.length > n-1 ? shifts[n-1] : 0);
         long destIndex = dest.index(x0, x1, ..., xn-1);
         long srcIndex = src.index(x'0, x'1, ..., x'n-1);
         Object element = src.array().getElement(srcIndex);
         dest.array().setElement(destIndex, element);
     }
 }
 

Here n=destRegion.n() is the number of dimensions. Please note that the number of dimensions of the matrices (src.dimCount() and dest.dimCount()) are ignored! It is possible, because Matrix.index(long...coordinates) method works with any number of passed coordinates: missing coordinates are supposed to be zero, extra coordinates (after first destRegion.n() ones) must be zero.

As you can see, the number of elements of shifts also can differ from the number of dimensions. All missing elements of shifts array are supposed to be zero.

The context argument is used as in Arrays.copy(ArrayContext, UpdatableArray, Array) method, but without multithreading. Namely, if context is not null, this method periodically calls its updateProgress and checkInterruption methods.

Warning: this method (as well as the loop listed above) can be non-atomic regarding IndexOutOfBoundsException. Namely, if some integer point x, belonging to destRegion, lies outside dest matrix, or the integer point x', obtained from it by subtracting shifts, lies outside src matrix, then IndexOutOfBoundsException is thrown, exactly as in the loop above (where Matrix.index(long...) method throws this exception). But some elements can be already copied before this moment.

All other possible exceptions are checked before any other actions. Moreover, if destRegion is Matrices.Hyperparallelepiped, then the region is also fully checked before starting the copying, and IndexOutOfBoundsException is thrown if necessary in the very beginning: so, this method is atomic regarding failures for hyperparallelepipeds.

Parameters:

context - the context of copying; may be null, then it will be ignored.

dest - the destination matrix.

src - the source matrix.

destRegion - the region in the destination matrix that should be copied from the source one.

shifts - the shift between the source and destination regions.

Throws:

NullPointerException - if dest, src, destRegion or shifts argument is null.

IllegalArgumentException - if the source and destination element types do not match, i.e. if dest.elementType() is not equal to src.elementType() and is not its superclass (for non-primitive element types).

IndexOutOfBoundsException - if some integer point x, belonging to destRegion, lies outside dest matrix, or the integer point x', obtained from it by subtracting shifts, lies outside src matrix (for regions, other than Matrices.Hyperparallelepiped, can be thrown in the middle of working after copying some elements).

See Also:

• copyRegion(ArrayContext, Matrix, Matrix, Region, long[], Object)

copyRegion

public static void copyRegion(ArrayContext context,
 Matrix<? extends UpdatableArray> dest,
 Matrix<? extends Array> src,
 Matrices.Region destRegion,
 long[] shifts,
 Object outsideValue)

An extended analog of copyRegion(ArrayContext, Matrix, Matrix, Region, long...) method, allowing to copy regions which do not lie fully inside dest and src matrices. Namely, instead of throwing IndexOutOfBoundsException, attempts to read elements outside src matrix produce outsideValue, and attempts to write elements outside dest matrix are just ignored.

For non-primitive element types, the outsideValue argument must be some instance of the class src.elementType(), or its superclass, or null. For primitive element types, outsideValue may be null or any wrapper for primitive types: Boolean, Byte, etc. The rules of conversion of this value to required primitive type are exactly the same as in Matrix.subMatrix(long[], long[], Matrix.ContinuationMode) method, the case of the constant continuation mode.

More precisely, this method is equivalent to the following loop (and, of course, works faster):

 for (all possible long coordinates x0, x1, ..., xn-1
     in ranges destRegion.coordRange(0), destRegion.coordRange(1),
     ..., destRegion.coordRange(n-1))
 {
     if (dest.inside(x0, x1, ..., xn-1) &&
         destRegion.contains(x0, x1, ..., xn-1)
     {
         long x'0 = x0 - (shifts.length > 0 ? shifts[0] : 0);
         long x'1 = x1 - (shifts.length > 1 ? shifts[1] : 0);
         ...
         long x'n-1 = xn-1 - (shifts.length > n-1 ? shifts[n-1] : 0);
         long destIndex = dest.index(x0, x1, ..., xn-1);
         Object element;
         if (src.inside(x'0, x'1, ..., x'n-1) {
             long srcIndex = src.index(x'0, x'1, ..., x'n-1);
             element = src.array().getElement(srcIndex);
         } else {
             element = outsideValue, casted by the rules of the constant submatrix continuation mode;
         }
         dest.array().setElement(destIndex, element);
     }
 }
 

Parameters:

context - the context of copying; may be null, then it will be ignored.

dest - the destination matrix.

src - the source matrix.

destRegion - the region in the destination matrix that should be copied from the source one.

shifts - the shift between the source and destination regions.

outsideValue - the value used while copying elements, lying outside src matrix.

Throws:

NullPointerException - if dest, src, destRegion or shifts argument is null.

IllegalArgumentException - if the source and destination element types do not match, i.e. if dest.elementType() is not equal to src.elementType() and is not its superclass (for non-primitive element types).

ClassCastException - if outsideValue is not null and its class is illegal, i.e. cannot be casted to the necessary type according the rules specified for the constant submatrix continuation mode.

clear

public static void clear(Matrix<? extends UpdatablePArray> result)

Fills all elements of the matrix with zero value. Equivalent to fill(result, o.0).

Parameters:

result - matrix to fill with zero.

fill

public static void fill(Matrix<? extends UpdatablePArray> result,
 double value)

Fills all elements of the matrix with the specified value. Equivalent to result.array().fill(value).

Parameters:

result - matrix to fill.

value - the value to be stored in all elements of the matrix.

fillRegion

public static void fillRegion(ArrayContext context,
 Matrix<? extends UpdatableArray> dest,
 Matrices.Region destRegion,
 Object value)

Fills the specified region in dest AlgART matrix with the specified value. Equivalent to the following call:

 copyRegion(context, dest, dest, destRegion, dest.dimensions(), value);
 

(In this call, shifting by dest.dimensions() means that the shifted point of the region lies fully outside the matrix, if the original point lies inside it. So, all elements will be filled by the value.)

For non-primitive element types, the value argument must be some instance of the class src.elementType(), or its superclass, or null. For primitive element types, value may be null or any wrapper for primitive types: Boolean, Byte, etc. The rules of conversion of this value to required primitive type are exactly the same as in Matrix.subMatrix(long[], long[], Matrix.ContinuationMode) method, the case of the constant continuation mode.

Parameters:

context - the context of filling; may be null, then it will be ignored.

dest - the destination matrix.

destRegion - the region in the destination matrix that should be filled by the specified value.

value - the value to be stored in all elements of the matrix inside the region.

Throws:

NullPointerException - if dest, src, destRegion or shifts argument is null.

ClassCastException - if value is not null and its class is illegal, i.e. cannot be casted to the necessary type according the rules specified for the constant submatrix continuation mode.

clearBoundary

public static void clearBoundary(Matrix<? extends UpdatablePArray> result,
 int boundaryWidth)

Equivalent to fillBoundary(result, boundaryWidth, 0.0).

Parameters:

result - the matrix to process.

boundaryWidth - width of the boundary to fill.

fillBoundary

public static void fillBoundary(Matrix<? extends UpdatablePArray> result,
 int boundaryWidth,
 double value)

Fills the boundary result matrix with the given width with the specified value.. If boundaryWidth==0, does nothing.

Equivalent to

 fillOutsideInMatrix(
     result,
     boundaryWidth,
     boundaryWidth,
     result.dimX() - 2 * (long) boundaryWidth,
     result.dimY() - 2 * (long) boundaryWidth,
     value)
 

Parameters:

result - the matrix to process.

boundaryWidth - width of the boundary to fill.

value - the value to be stored in all elements near the matrix boundary.

Throws:

IllegalArgumentException - if boundaryWidth<0.

fillOutside

public static void fillOutside(Matrix<? extends UpdatablePArray> result,
 long minX,
 long minY,
 long sizeX,
 long sizeY,
 double value)

Fills all result matrix, excepting elements in the rectangle minX≤x<minX+sizeX, minY≤y<minY+sizeY, with the specified value. If sizeX≤0 or sizeY≤0, fills all the matrix.

Parameters:

result - the matrix to process.

minX - minimal x-coordinate, which is not filled.

minY - minimal y-coordinate, which is not filled.

sizeX - width of the rectangle, which is not filled.

sizeY - height of the rectangle, which is not filled.

value - the value to be stored in all elements outside this rectangle.

Throws:

IndexOutOfBoundsException - if sizeX>0, sizeY>0 and the specified area is not fully inside the matrix.

dimensionsToString

public static String dimensionsToString(long[] dim)