Package net.algart.matrices

Enum Class DependenceApertureBuilder

java.lang.Object
java.lang.Enum<DependenceApertureBuilder>
net.algart.matrices.DependenceApertureBuilder
All Implemented Interfaces:
Serializable, Comparable<DependenceApertureBuilder>, Constable
public enum DependenceApertureBuilder extends Enum<DependenceApertureBuilder>

Helper class for calculation of the rectangular dependence aperture of some matrix processing algorithms.

Many algorithms, processing n-dimensional matrices, calculate a resulting matrix, where the value of every element depends only on the elements of some source matrix (or matrices), lying inside some rectangular aperture around the coordinates of the resulting element. The typical examples are aperture-dependent processors, represented by ApertureProcessor interface, and a group of algorithms, described by StreamingApertureProcessor class. We call such an aperture the dependence aperture of a given processing algorithm.

More precisely, the dependence aperture is such rectangular area in n-dimensional space, represented by IRectangularArea object A, that every element of the resulting n-dimensional matrix with coordinates x = (x0, x1, ..., xn−1) can depend only on elements of the source matrix (or matrices) with coordinates

x+a = x0+a0, x1+a1, ..., xn−1+an−1,

where a = (a0, a1, ..., an−1) is one of points belonging to the rectangular area A. Please draw attention that we use plus sing + in this definition, instead of more traditional minus sign − (used, for example, in specifications of StreamingApertureProcessor or RankMorphology).

The goal of this class is to build such rectangular aperture A on the base of one or several apertures (patterns), represented by Pattern interface and specifying, for example, possible dependence aperture for different stages of the full processing algorithm. Draw attention: for the apertures, specified as patterns, we suppose more traditional definitions with minus sign −, as in specifications of StreamingApertureProcessor or RankMorphology (a set of points x−p = (x0−p0, x1−p1, ..., xn−1−pn−1) for all p∈P, P is a pattern).

The main method, solving this task, is

getAperture(int dimCount, Pattern[] patterns, boolean[] inverted, short additionalSpace)

The resulting rectangular aperture is built on the base of the rounded coordinate ranges of every pattern (Pattern.roundedCoordRange(int)) according to combination rules, depending on a concrete instance of this enumeration. Please see comments to the constants of this enumeration class:

This class is immutable and thread-safe: there are no ways to modify settings of the created instance.

Author:
Daniel Alievsky

  • Enum Constant Details

    • SUM

      public static final DependenceApertureBuilder SUM
      Aperture builder, calculating sum of coordinate ranges of all passed patterns.

      More precisely, in this builder the basic getAperture(int dimCount, Pattern[] patterns, boolean[] inverted, short additionalSpace) method works according the following algorithm: 

       long[] allMin = new long[dimCount]; // zero-filled by Java
 long[] allMax = new long[dimCount]; // zero-filled by Java
 for (int k = 0; k < dimCount; k++) {
     for (int i = 0; i < patterns.length; i++) {
         IRange range = patterns[i].roundedCoordRange(k);
         long min = inverted[i] ? range.min() : -range.max();
         long max = inverted[i] ? range.max() : -range.min();
         allMin[k] += min;
         allMax[k] += max;
     }
     allMin[k] -= additionalSpace;
     allMax[k] += additionalSpace;
 }
 return IRectangularArea.valueOf(IPoint.valueOf(allMin), IPoint.valueOf(allMax));

      The only difference from this code is that this class checks possible overflow before every usage of Java + and - operators with long values and, in a case of overflow, throws IndexOutOfBoundsException.

      This mode is suitable for algorithms, which perform several sequential operations over the matrix, when each elements of the result of each operation #k with coordinates x = (x0, x1, ..., xn−1) depends on the elements of the previous matrix with coordinates x−pi = (x0−pi0, x1−pi1, ..., xn−1−pi,n−1). Here pi are all points of the corresponding pattern patterns[k] or, if inverted[k] is true, of the symmetric pattern patterns[k].symmetric().

      An example of algorithm, where this aperture builder can be useful, is Morphology.dilationErosion(Matrix, Pattern, Pattern, net.algart.matrices.morphology.Morphology.SubtractionMode) (if the last argument is Morphology.SubtractionMode.NONE).

    • MAX

      public static final DependenceApertureBuilder MAX
      Aperture builder, calculating set-theoretical union of coordinate ranges of all passed patterns, with an additional guarantee that the result will contain the origin of coordinates.

      More precisely, in this builder the basic getAperture(int dimCount, Pattern[] patterns, boolean[] inverted, short additionalSpace) method works according the following algorithm: 

       long[] allMin = new long[dimCount]; // zero-filled by Java
 long[] allMax = new long[dimCount]; // zero-filled by Java
 for (int k = 0; k < dimCount; k++) {
     for (int i = 0; i < patterns.length; i++) {
         IRange range = patterns[i].roundedCoordRange(k);
         long min = inverted[i] ? range.min() : -range.max();
         long max = inverted[i] ? range.max() : -range.min();
         allMin[k] = Math.min(allMin[k], min);
         allMax[k] = Math.max(allMax[k], max);
     }
     allMin[k] -= additionalSpace;
     allMax[k] += additionalSpace;
 }
 return IRectangularArea.valueOf(IPoint.valueOf(allMin), IPoint.valueOf(allMax));

      The only difference from this code is that this class checks possible overflow before every usage of Java + and - operators with long values and, in a case of overflow, throws IndexOutOfBoundsException.

      This mode is suitable for algorithms, which perform several independent operations over the same original matrix, when each elements of the result of each operation #k with coordinates x = (x0, x1, ..., xn−1) depends on the elements of the previous matrix with coordinates x−pi = (x0−pi0, x1−pi1, ..., xn−1−pi,n−1). Here pi are all points of the corresponding pattern patterns[k] or, if inverted[k] is true, of the symmetric pattern patterns[k].symmetric().

      An example of algorithm, where this aperture builder can be useful, is Morphology.beucherGradient(Matrix, Pattern).

    • SUM_MAX_0

      public static final DependenceApertureBuilder SUM_MAX_0
      Aperture builder, calculating sum of coordinate ranges of all passed patterns, with an additional guarantee that the result will contain the origin of coordinates.

      More precisely, in this builder the basic getAperture(int dimCount, Pattern[] patterns, boolean[] inverted, short additionalSpace) method works according the following algorithm: 

       long[] allMin = new long[dimCount]; // zero-filled by Java
 long[] allMax = new long[dimCount]; // zero-filled by Java
 for (int k = 0; k < dimCount; k++) {
     for (int i = 0; i < patterns.length; i++) {
         IRange range = patterns[i].roundedCoordRange(k);
         long min = inverted[i] ? range.min() : -range.max();
         long max = inverted[i] ? range.max() : -range.min();
         allMin[k] += min;
         allMax[k] += max;
     }
     allMin[k] = Math.min(allMin[k], 0);
     allMax[k] = Math.max(allMax[k], 0);
     allMin[k] -= additionalSpace;
     allMax[k] += additionalSpace;
 }
 return IRectangularArea.valueOf(IPoint.valueOf(allMin), IPoint.valueOf(allMax));

      The only difference from this code is that this class checks possible overflow before every usage of Java + and - operators with long values and, in a case of overflow, throws IndexOutOfBoundsException.

      This mode is suitable for algorithms, which perform several sequential operations over the matrix, when each elements of the result of each operation #k with coordinates x = (x0, x1, ..., xn−1) depends on the elements of the previous matrix with coordinates x−pi = (x0−pi0, x1−pi1, ..., xn−1−pi,n−1). Here pi are all points of the corresponding pattern patterns[k] or, if inverted[k] is true, of the symmetric pattern patterns[k].symmetric().

      An example of algorithm, where this aperture builder can be useful, is Morphology.maskedDilationErosion(Matrix, Pattern, Pattern).

  • Field Details

    • DEFAULT_ADDITIONAL_SPACE

      public static final short DEFAULT_ADDITIONAL_SPACE
      Default additional space, used by getAperture(int, Pattern[], boolean[]) method: 2 elements. This gap is enough for most cases, when a processing algorithm uses not only the elements from the corresponding apertures (specified by Pattern objects), but probably also their neighbours and neighbours of neighbours.
      See Also:

  • Method Details

    • values

      public static DependenceApertureBuilder[] values()
      Returns an array containing the constants of this enum class, in the order they are declared.
      Returns:
      an array containing the constants of this enum class, in the order they are declared

    • valueOf

      public static DependenceApertureBuilder valueOf(String name)
      Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
      Parameters:
      name - the name of the enum constant to be returned.
      Returns:
      the enum constant with the specified name
      Throws:
      IllegalArgumentException - if this enum class has no constant with the specified name
      NullPointerException - if the argument is null

    • getAperture

      public IRectangularArea getAperture(int dimCount, Pattern pattern, boolean inverted)
      Equivalent to getAperture(dimCount, new Pattern[]{pattern}, new boolean[]{inverted}, DEFAULT_ADDITIONAL_SPACE).
      Parameters:
      dimCount - the number of dimensions.
      pattern - the pattern, describing the dependence apertures the algorithm.
      inverted - if true, then patterns is supposed to be inverted.
      Returns:
      rectangular dependence aperture, describing dependence of the elements of the full processing algorithm.
      Throws:
      NullPointerException - if pattern argument is null.
      IllegalArgumentException - if dimCount<=0, or the passed pattern has number of dimensions, less than dimCount argument.
      IndexOutOfBoundsException - in a case of integer (63-bit) overflow while calculation of the resulting aperture: see SUM, MAX and SUM_MAX_0 constants.

    • getAperture

      public IRectangularArea getAperture(int dimCount, Pattern pattern1, boolean inverted1, Pattern pattern2, boolean inverted2)
      Equivalent to getAperture(dimCount, new Pattern[]{pattern1, pattern2}, new boolean[]{inverted1, inverted2}, DEFAULT_ADDITIONAL_SPACE).
      Parameters:
      dimCount - the number of dimensions.
      pattern1 - the pattern, describing the dependence apertures of the 1st part (stage) of the full algorithm.
      inverted1 - if true, then pattern1 is supposed to be inverted.
      pattern2 - the pattern, describing the dependence apertures of the 2nd part (stage) of the full algorithm.
      inverted2 - if true, then pattern2 is supposed to be inverted.
      Returns:
      rectangular dependence aperture, describing dependence of the elements of the full processing algorithm, consisting of 2 parts (stages).
      Throws:
      NullPointerException - if patterns1 or pattern2 argument is null.
      IllegalArgumentException - if dimCount<=0, or if some of the passed patterns have number of dimensions, less than dimCount argument.
      IndexOutOfBoundsException - in a case of integer (63-bit) overflow while calculation of the resulting aperture: see SUM, MAX and SUM_MAX_0 constants.

    • getAperture

      public IRectangularArea getAperture(int dimCount, Pattern[] patterns, boolean[] inverted)
      Equivalent to getAperture(dimCount, patterns, inverted, DEFAULT_ADDITIONAL_SPACE).
      Parameters:
      dimCount - the number of dimensions.
      patterns - the set of patterns, describing the dependence apertures of different parts (stages) of the full algorithms, for example, in terms of StreamingApertureProcessor class.
      inverted - if some element inverted[k] is true, then the corresponding element patterns[k] is supposed to be inverted.
      Returns:
      rectangular dependence aperture, describing dependence of the elements of the full processing algorithm, consisting of patterns.length parts (stages).
      Throws:
      NullPointerException - if patterns or inverted argument is null, or if some elements of patterns array is null.
      IllegalArgumentException - if dimCount<=0, or if patterns and inverted arrays have different lengths, or if their length is zero (patterns.length==0), or if some of the passed patterns have number of dimensions, less than dimCount argument.
      IndexOutOfBoundsException - in a case of integer (63-bit) overflow while calculation of the resulting aperture: see SUM, MAX and SUM_MAX_0 constants.

    • getAperture

      public IRectangularArea getAperture(int dimCount, Pattern[] patterns, boolean[] inverted, short additionalSpace)
      Builds the rectangular aperture on the base of specified array of apertures-patterns. If inverted[k] is true, then the corresponding pattern is supposed to be inverted (i.e. replaced with its symmetric version). Please see comments to SUM, MAX and SUM_MAX_0 constants for detailed specification of the behaviour of this method.
      Parameters:
      dimCount - the number of dimensions.
      patterns - the set of patterns, describing the dependence apertures of different parts (stages) of the full algorithms, for example, in terms of StreamingApertureProcessor class.
      inverted - if some element inverted[k] is true, then the corresponding element patterns[k] is supposed to be inverted.
      additionalSpace - additional gap, added to all coordinate ranges of the resulting aperture.
      Returns:
      rectangular dependence aperture, describing dependence of the elements of the full processing algorithm, consisting of patterns.length parts (stages).
      Throws:
      NullPointerException - if patterns or inverted argument is null, or if some elements of patterns array is null.
      IllegalArgumentException - if dimCount<=0, or if patterns and inverted arrays have different lengths, or if their length is zero (patterns.length==0), or if additionalSpace<0, or if some of the passed patterns have number of dimensions, less than dimCount argument.
      IndexOutOfBoundsException - in a case of integer (63-bit) overflow while calculation of the resulting aperture: see SUM, MAX and SUM_MAX_0 constants.

    • extendDimensions

      public static long[] extendDimensions(long[] matrixDimensions, IRectangularArea aperture)
      Returns a newly created array result with the same length as the first argument, where result[k] = matrixDimensions[k])+aperture.width(k). This method also checks that all dimensions in the matrixDimensions array, as well as the resulting dimensions result array, are allowed dimensions for some AlgART matrix, i.e. are non-negative and their product is not greater than Long.MAX_VALUE. If it is not so, IndexOutOfBoundsException is thrown.

      In the special case, when some of elements of the matrixDimensions array is zero, this method returns a precise clone of this array without changes.

      Note: the matrix, returned by extend(Matrix, IRectangularArea, Matrix.ContinuationMode) method, always has dimensions, equal to the result of this method, called for dimensions of the source matrix with the same aperture.

      Parameters:
      matrixDimensions - dimensions of some n-dimensional matrix.
      aperture - the dependence aperture.
      Returns:
      new dimensions, extended by the given aperture.
      Throws:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if matrixDimensions.length!=aperture.coordCount(), or if matrixDimensions[k]<0 for some k.
      IndexOutOfBoundsException - if product of all elements of matrixDimensions array is greater than Long.MAX_VALUE, or in a case of integer overflow while calculating result[k], or if product of all elements of the resulting array is greater than Long.MAX_VALUE.

    • extend

      public static <T extends PArray> Matrix<T> extend(Matrix<T> matrix, IRectangularArea aperture, Matrix.ContinuationMode continuationMode)
      Returns matrix.subMatrix(from, to, continuationMode), where from[k] = aperture.min(k) and to[k] = matrix.dim(k)+aperture.max(k). This method allows to extends the source matrix in such a way, that every element of the resulting matrix of some processing algorithm, having the given dependence aperture, will depend only on the existing elements of the extended matrix (lying inside its bounds).

      In the special case matrix.size()==0, this method returns the matrix argument without changes.

      This method performs additional checks, whether adding aperture.max().coord(k) to the matrix dimension leads to integer overflow, and throws IndexOutOfBoundsException in a case of overflow.

      Parameters:
      matrix - some n-dimensional matrix.
      aperture - the dependence aperture.
      continuationMode - the continuation mode for extending the matrix.
      Returns:
      new matrix, extended by the given aperture.
      Throws:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if matrix.dimCount()!=aperture.coordCount().
      IndexOutOfBoundsException - in a case of integer overflow while calculating to[k], or in the same situations as the corresponding subMatrix call.
      ClassCastException - in the same situations as the corresponding subMatrix call..
      See Also:

    • reduce

      public static <T extends PArray> Matrix<T> reduce(Matrix<T> matrix, IRectangularArea aperture)
      Returns matrix.subMatrix(from, to, Matrix.ContinuationMode.PSEUDO_CYCLIC), where from[k] = -aperture.min(k) and to[k] = matrix.dim(k)-aperture.max(k). It is the reverse method for extend(Matrix, IRectangularArea, Matrix.ContinuationMode).

      In the special case matrix.size()==0, this method returns the matrix argument without changes.

      Parameters:
      matrix - some n-dimensional matrix, extended by extend(Matrix, IRectangularArea, Matrix.ContinuationMode) method.
      aperture - the dependence aperture.
      Returns:
      new matrix, reduced to the original sizes.
      Throws:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if matrix.dimCount()!=aperture.coordCount().
      IndexOutOfBoundsException - in the same situations as the corresponding subMatrix call.

    • safelyAdd

      public static long safelyAdd(long a, long b) throws IndexOutOfBoundsException
      Returns sum of the arguments a+b, if this sum can be precisely represented by long type, i.e. if it lies in Long.MIN_VALUE..Long.MAX_VALUE range, or throws IndexOutOfBoundsException in other case. (Unlike this method, the simple Java operator a+b always returns low 64 bits of the mathematical sum a+b without any checks and exceptions.)

      This method is useful for accurate calculating matrix dimensions and integer rectangular areas, for example, for calculating dimensions of a matrix, extended with some rectangular aperture.

      Parameters:
      a - first summand.
      b - second summand.
      Returns:
      sum a+b.
      Throws:
      IndexOutOfBoundsException - in a case of integer overflow, i.e. if the mathematical sum a+b of this integers is less than Long.MIN_VALUE or greater than Long.MAX_VALUE.