Package net.algart.math.patterns

Interface UniformGridPattern

All Superinterfaces:
Pattern
All Known Subinterfaces:
DirectPointSetUniformGridPattern, RectangularPattern
All Known Implementing Classes:
AbstractUniformGridPattern
public interface UniformGridPattern extends Pattern

Interface, used by Pattern implementations to indicate that they are uniform-grid patterns, i.e. subsets of the set of all mesh nodes of some uniform grids. See also the section "Uniform-grid patterns" in the comments to Pattern interface.

More precisely, a pattern, implementing this interface, is some set of N points (N>0) x(k) = (x0(k), x1(k), ..., xn−1(k)) (k=0,1,...,N−1, n=dimCount()), produced by the following formulas:

x0(k) = o0 + i0(k)d0
x1(k) = o1 + i1(k)d1
. . .
xn−1(k) = on−1 + in−1(k)dn−1

where oj and dj are some constants (dj>0) and ij(k) are any integer numbers. The point o=(o0,o1,...,on−1), named origin of the grid, and the vector d=(d0,d1,...,dn−1), named steps of the grid, are specified while creating the pattern. Moreover, these parameters about (o and d) are stored inside the object and can be quickly read at any time by originOfGrid() and stepsOfGrid() methods — this condition is a requirement for all implementations of this interface.

The numbers ij(k) are called grid indexes of the points of the pattern (or, briefly, grid indexes of the pattern). The integer points i(k) = (i0(k), i1(k), ..., in−1(k)) (k=0,1,...,N−1) form an integer pattern (see the section "Integer patterns" in the comments to Pattern interface), which is called grid index pattern and can be got at any time by gridIndexPattern() method. If the number of points is not extremely large, the grid indexes can be also retrieved directly as Java set of i(k) points by gridIndexes() method.

Warning: not only patterns, implementing this interface, are actually such sets of points. Moreover, many patterns, created by this package, are really uniform grid (all their points really belong to set of mesh points of some uniform grid), but they do not implement this interface and are not considered to be "uniform-grid". The typical examples are Minkowski sums, created by Patterns.newMinkowskiSum(Collection) method, and unions, created by Patterns.newUnion(Collection) method. It is obvious that a Minkowski sum or a union of several uniform-grid patterns, having zero origin o=(0,0,...,0) and the same steps d, are also uniform-grid patterns with the same origin and steps. However, it is very probably that the objects, returned by Patterns.newMinkowskiSum(Collection) and Patterns.newUnion(Collection) methods, will not implement UniformGridPattern interface even in this "good" case.

Grid index restrictions

There are the following guarantees for grid indexes ij(k) of any uniform-grid pattern:

  1. if p=(i0,i1,...,in−1) is the grid index of some point of the pattern, then −Pattern.MAX_COORDINATE≤ij≤Pattern.MAX_COORDINATE for all j;
  2. if p=(i01,i11,...,in−11) and q=(i02,i12,...,in−12) are the grid indexes of some two points of the pattern, then |ij1−ij2|≤Pattern.MAX_COORDINATE for all j.

Each implementation of this interface must fulfil both restriction. Any attempt to create a uniform-grid pattern, the grid indexes of which do not satisfy these restrictions, leads to TooLargePatternCoordinatesException.

These restrictions are guaranteed together with the coordinate restrictions, described in the section "Coordinate restrictions" in the comments to Pattern interface. These restrictions provide a guarantee that the method gridIndexPattern() always works successfully and creates a correct integer pattern.

Author:
Daniel Alievsky

  • Method Details

    • originOfGrid

      Point originOfGrid()
      Returns the grid origin o of this pattern. See the comments to this interface for more details.

      There is a guarantee, that this method always works very quickly (O(dimCount()) operations) and without exceptions.

      Returns:
      the origin o of the uniform grid of this pattern.

    • stepsOfGrid

      double[] stepsOfGrid()
      Returns the array of grid steps d of this pattern. The length of the returned array is equal to dimCount(), and the element #j contains the grid step dj along the coordinate #j. See the comments to this interface for more details.

      The returned array is a clone of the internal array of the steps, stored in this object. The returned array is never empty (its length cannot be zero). The elements of the returned array are always positive (<0.0).

      There is a guarantee, that this method always works very quickly (O(dimCount()) operations) and without exceptions.

      Returns:
      an array containing all grid steps of this pattern.

    • stepOfGrid

      double stepOfGrid(int coordIndex)
      Returns the grid step dj along the coordinate #j of this pattern along the coordinate #j=coordIndex. Equivalent to stepsOfGrid()[coordIndex], but works faster.

      There is a guarantee, that this method always works very quickly (maximally O(dimCount()) operations) and without exceptions.

      Returns:
      the grid step of this pattern along the specified coordinate axis.
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=dimCount().

    • stepsOfGridEqual

      boolean stepsOfGridEqual(UniformGridPattern pattern)
      Indicates whether the other uniform-grid pattern has the same grid steps. In other words, returns true if and only if both patterns have the same dimension count (dimCount()) and the corresponding grid steps stepOfGrid((k) are equal for every k.

      Note: this method does not compare the origin of grid.

      Equality of grid steps is important, for example, while calculation of a Minkowski sum of this and another patterns by Pattern.minkowskiAdd(Pattern) method. If two uniform-grid patterns have identical grid steps, then a Minkowski sum of them can be also represented by uniform-grid pattern (with same grid steps). In other case, it is usually impossible — the Minkowski sum, returned by Pattern.minkowskiAdd(Pattern), will not implement UniformGridPattern.

      Parameters:
      pattern - another uniform-grid pattern, the grid steps of which should be compared with grid steps of this one.
      Returns:
      true if the specified pattern has the same steps of grid.

    • gridIndexes

      Set<IPoint> gridIndexes()
      Returns a set of all grid indexes ij of this pattern. Namely, the elements of the returned set contain grid indexes i(k) = (i0(k), i1(k), ..., in−1(k)) of all points x(k) = (x0(k), x1(k), ..., xn−1(k)) of this pattern:
      x0(k) = o0 + i0(k)d0
      x1(k) = o1 + i1(k)d1
      . . .
      xn−1(k) = on−1 + in−1(k)dn−1

      The result of this method is immutable (Collections.unmodifiableSet). Moreover, the result is always the same for different calls of this method for the same instance — there are no ways to change it, in particular, via any custom methods of the implementation class (it is a conclusion from the common requirement, that all implementations of Pattern interface must be immutable).

      The returned set is always non-empty, and the number of its elements is always equal to Pattern.pointCount().

      Warning! This method can work slowly for some forms of large patterns. In these cases, this method can also throw TooManyPointsInPatternError or OutOfMemoryError. This method surely fails (throws one of these exception), if the total number of points Pattern.pointCount()>Integer.MAX_VALUE, because Java Set object cannot contain more than Integer.MAX_VALUE elements.

      For example, implementations of the rectangular patterns allow to successfully define a very large 3D parallelepiped n x n x n. Fur such pattern, this method will require a lot of memory for n=1000 and will fail (probably with TooManyPointsInPatternError) for n=2000 (20003>Integer.MAX_VALUE).

      There is a guarantee, that if this object implements DirectPointSetPattern interface, then this method requires not greater than O(N) operations and memory (N=pointCount()) and never throws TooManyPointsInPatternError.

      Note: if you do not really need to get a Java collection of all grid indexes, you can use gridIndexPattern() method, which returns the same result in a form of another (integer) pattern. That method, unlike this one, never spends extreme amount of memory and time and has no risk to fail with TooManyPointsInPatternError / OutOfMemoryError.

      Returns:
      all grid indexes of this pattern.
      Throws:
      TooManyPointsInPatternError - if the number of points is greater than Integer.MAX_VALUE or, in some rare situations, is near this limit (OutOfMemoryError can be also thrown instead of this exception).
      See Also:

    • gridIndexRange

      IRange gridIndexRange(int coordIndex)
      Returns the minimal and maximal grid index ij among all points of this pattern for the specified coordinate index j==coordIndex. The minimal grid index will be r.min(), the maximal grid index will be r.max(), where r is the result of this method. See the comments to this interface for more details.

      There is a guarantee, that if this object implements RectangularPattern interface, then this method works very quickly (O(1) operations) and without exceptions.

      Moreover, all patterns, implemented in this package, have very quick implementations of this method (O(1) operations). Also, the implementations of this method in this package never throw exceptions.

      It is theoretically possible, that in custom implementations of this interface (outside this package) this method will work slowly, up to O(N) operations, N is the number of points in this pattern. However, even in such implementations this method must not lead to TooManyPointsInPatternError / OutOfMemoryError, like Pattern.points() method.

      Parameters:
      coordIndex - the index j of the coordinate (0 for x, 1 for y, 2 for z, etc.).
      Returns:
      the range from minimal to maximal grid index ij.
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=dimCount().
      See Also:

    • gridIndexArea

      IRectangularArea gridIndexArea()
      Returns the minimal and maximal grid index ij among all points of this pattern for all coordinate axes j If a is the result of this method, then a.coordCount()==dimCount() and a.range(k) is equal to gridIndexRange(k) for all k.

      All, said in the comments to gridIndexRange(int) method about the speed and impossibility of TooManyPointsInPatternError / OutOfMemoryError, is also true for this method.

      Returns:
      the ranges from minimal to maximal grid index for all space dimensions.

    • gridIndexMin

      IPoint gridIndexMin()
      Returns the point, each coordinate #j of which is equal to the minimal corresponding grid index ij among all points of this pattern. Equivalent to gridIndexArea().min().

      All, said in the comments to gridIndexRange(int) method about the speed and impossibility of TooManyPointsInPatternError / OutOfMemoryError, is also true for this method.

      Returns:
      minimal grid index for all space dimensions as a point.

    • gridIndexMax

      IPoint gridIndexMax()
      Returns the point, each coordinate #j of which is equal to the maximal corresponding grid index ij among all points of this pattern. Equivalent to gridIndexArea().max().

      All, said in the comments to gridIndexRange(int) method about the speed and impossibility of TooManyPointsInPatternError / OutOfMemoryError, is also true for this method.

      Returns:
      maximal grid index for all space dimensions as a point.

    • isOrdinary

      boolean isOrdinary()
      Returns true if and only if this uniform-grid pattern is an ordinary integer pattern, i.e. if the grid origin o is the origin of coordinates (0,0,...,0) and all grid steps dj are 1.0. Equivalent to originOfGrid().isOrigin() && gridIndexRange(0)==1.0 && gridIndexRange(1)==1.0 && ... Ordinary integer patterns are a simplest form of integer pattern: see comments to Pattern interface, section "Uniform-grid patterns".

      There is a guarantee, that this method always works very quickly (maximally O(dimCount()) operations) and without exceptions.

      Returns:
      whether the grid origin o=(0,0,...,0) and also all grid steps dj=1.0.

    • isActuallyRectangular

      boolean isActuallyRectangular()
      Returns true if this pattern is n-dimensional rectangular parallelepiped. (For 2D patterns it means a rectangle, for 1D pattern it means an interval.) In other words, it returns true if this pattern is the set of all points (o0+i0d0, o1+i1d1, ..., on−1+in−1dn−1), where oj are coordinates of the origin of the grid, dj are steps of the grid and ij are all integers in the ranges gridIndexRange(j).min()<=ij<=gridIndexRange(j).max(), j=0,1,...,dimCount()−1.

      Note that this condition is the same as in the definition of rectangular patterns, represented by RectangularPattern interface. Really, if the object implements RectangularPattern, this method always returns true. However, this method tries to investigate the actual point set for other types of patterns.

      There are no strict guarantees that this method always returns true if the pattern is n-dimensional rectangular parallelepiped. (In some complex situations, such analysis can be too difficult.) But there is this guarantee for all uniform-grid patterns, created by this package. And, of course, there is the reverse guarantee: if this method returns true, the pattern is really a rectangular parallelepiped.

      You may be also sure that this method always works quickly enough and without exceptions. In the worst case, it can require O(N) operations, N=pointCount(), but usually it works much more quickly. (So, if you implement this method yourself and there is a risk, that calculations can lead to TooManyPointsInPatternError, OutOfMemory or another exception due to extremely large number of points, you must return false instead of throwing an exception. Please compare this with Pattern.pointCount() and Pattern.points() methods, which do not provide such guarantees and may lead to an exception.)

      Returns:
      true if this pattern is n-dimensional rectangular parallelepiped.

    • gridIndexPattern

      UniformGridPattern gridIndexPattern()
      Returns an ordinary integer pattern with the same set of grid indexes ij(k) as this pattern. In other words, if this pattern is a set of points
      x0(k) = o0 + i0(k)d0
      x1(k) = o1 + i1(k)d1
      . . .
      xn−1(k) = on−1 + in−1(k)dn−1

      (k=0,1,...,N−1, n=dimCount()), then the returned pattern consists of points

      y0(k) = (double)i0(k)
      y1(k) = (double)i1(k)
      . . .
      yn−1(k) = (double)in−1(k)

      Note: here is a guarantee, that all grid indexes ij will be strictly represented by double type. Moreover, there is a guarantee that the returned pattern is correct, i.e. will be successfully built without a risk of TooLargePatternCoordinatesException. See the comments to Pattern.MAX_COORDINATE and the section "Grid index restrictions" in the comments to UniformGridPattern interface.

      You can use this method to get a set of all grid indexes (integer values): it is enough to call Pattern.roundedPoints() in the returned pattern. The results will be the same as the result of gridIndexes() method.

      The returned pattern always implements DirectPointSetPattern if this pattern implements DirectPointSetPattern.

      The returned pattern always implements RectangularPattern if this pattern implements RectangularPattern.

      There is a guarantee, that this method does not try to allocate much more memory, that it is required for storing this pattern itself, and that it never throws TooManyPointsInPatternError.

      This method works quickly enough: in the worst case, it can require O(N) operations (N=pointCount()).

      Returns:
      an ordinary integer pattern, consisting of all grid indexes of this pattern (represented by double values).
      See Also:

    • shiftGridIndexes

      UniformGridPattern shiftGridIndexes(IPoint shift)
      Returns another uniform-grid pattern, identical to this one with the only difference, that the grid index i(k) = (i0(k), i1(k), ..., in−1(k)) for each point #k of the result is shifted by the argument of this method via the call i(k).add(shift). In other words, if this pattern is a set of points
      x0(k) = o0 + i0(k)d0
      x1(k) = o1 + i1(k)d1
      . . .
      xn−1(k) = on−1 + in−1(k)dn−1

      (k=0,1,...,N−1, n=dimCount()), then the returned pattern has the same grid oridin, the same grid steps and consists of points

      y0(k) = o0 + (i0(k)+shift.coord(0))*d0
      y1(k) = o1 + (i1(k)+shift.coord(1))*d1
      . . .
      yn−1(k) = on−1 + (in−1(k)+shift.coord(n−1))*dn−1

      The returned pattern always implements DirectPointSetPattern if this pattern implements DirectPointSetPattern

      The returned pattern always implements RectangularPattern if this pattern implements RectangularPattern.

      There is a guarantee, that this method does not try to allocate much more memory, that it is required for storing this pattern itself, and that it never throws TooManyPointsInPatternError. For comparison, an attempt to do the same operation via getting all grid indexes via gridIndexes() call, correcting them and forming a new pattern via Patterns.newUniformGridPattern(Point, double[], java.util.Collection) will lead to TooManyPointsInPatternError / OutOfMemoryError for some forms of large patterns.

      Warning: this method can fail with TooLargePatternCoordinatesException, if some of new points violate restrictions, described in the comments to Pattern interface, section "Coordinate restrictions", and in the comments to UniformGridPattern interface, section "Coordinate restrictions" (for example, due to very large shift).

      Note: the similar results can be got with help of shift(Point) method with a corresponding floating-point shift. However, this method guarantees that the returned pattern has the same origin of the grid, but corrected grid indexes. Unlike this, a good implementation of shift(Point) method just corrects the grid origin, but does not change grid indexes. This difference is important, if you are going to get the grid indexes from the shifted pattern via gridIndexPattern() or gridIndexes() method.

      Parameters:
      shift - the shift of the grid indexes.
      Returns:
      the shifted pattern.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if point.coordCount()!=Pattern.dimCount().
      TooLargePatternCoordinatesException - if the set of shifted points does not fulfil the restrictions, described in the comments to Pattern interface, section "Coordinate restrictions", and in the comments to UniformGridPattern interface, section "Coordinate restrictions".

    • lowerSurface

      UniformGridPattern lowerSurface(int coordIndex)
      Returns the lower boundary of this pattern along the given axis: a pattern consisting of all such points A of this pattern, that the neighbour point B, generated by the backward shift of point A along the coordinate #j=coordIndex by the corresponding grid step dj=stepOfGrid(coordIndex), does not belong to this pattern. The number of dimensions in the resulting pattern (dimCount()) is the same as in this one.

      In other words, the point A = (x0, x1, ..., xj, ..., xn−1) belongs to the returned pattern if and only if it belongs to this pattern and the point B = (x0, x1, ..., xj−dj, ..., xn−1) (corresponding to decreasing the grid index ij by 1) does not belong to this pattern.

      Please compare with minBound(int) method. This method can return a pattern containing more points than minBound(int), in particular, if this pattern contains some "holes".

      The returned pattern always implements DirectPointSetPattern if this pattern implements DirectPointSetPattern

      The returned pattern always implements RectangularPattern if this pattern implements RectangularPattern.

      Note: if this object is not DirectPointSetPattern and is not RectangularPattern, this method can work slowly for some large patterns: the required time can be O(N), where N is the number of points. In these cases, this method can also throw TooManyPointsInPatternError or OutOfMemoryError. The situation is like in Pattern.points() and Pattern.roundedPoints() method. However, this situation is possible only in custom implementation of this interface — all implementations, provided by this package, implement either DirectPointSetPattern or RectangularPattern interface.

      There is a guarantee, that if this object implements DirectPointSetPattern interface, then this method requires not greater than O(N) memory (N=pointCount()) and never throws TooManyPointsInPatternError.

      There is a guarantee, that if this object implements RectangularPattern interface, then this method works quickly (O(1) operations) and without exceptions.

      Parameters:
      coordIndex - the index of the coordinate (0 for x, 1 for y, 2 for z, etc.)
      Returns:
      the "lower boundary" of this pattern: new pattern consisting of all points of this pattern, which have no leftward neighbour along the given coordinate.
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=dimCount().
      TooManyPointsInPatternError - (impossible for implementations, provided by this package) if this pattern is not DirectPointSetPattern and not RectangularPattern and if, at the same time, the number of points is greater than Integer.MAX_VALUE or, in some rare situations, is near this limit (OutOfMemoryError can be also thrown instead of this exception).

    • upperSurface

      UniformGridPattern upperSurface(int coordIndex)
      Returns the upper boundary of this pattern along the given axis: a pattern consisting of all such points A of this pattern, that the neighbour point B, generated by the forward shift of point A along the coordinate #j=coordIndex by the corresponding grid step dj=stepOfGrid(coordIndex), does not belong to this pattern. The number of dimensions in the resulting pattern (dimCount()) is the same as in this one.

      In other words, the point A = (x0, x1, ..., xj, ..., xn−1) belongs to the returned pattern if and only if it belongs to this pattern and the point B = (x0, x1, ..., xj+dj, ..., xn−1) (corresponding to increasing the grid index ij by 1) does not belong to this pattern.

      Please compare with maxBound(int) method. This method can return a pattern containing more points than maxBound(int), in particular, if this pattern contains some "holes".

      The returned pattern always implements DirectPointSetPattern if this pattern implements DirectPointSetPattern

      The returned pattern always implements RectangularPattern if this pattern implements RectangularPattern.

      Note: if this object is not DirectPointSetPattern and is not RectangularPattern, this method can work slowly for some large patterns: the required time can be O(N), where N is the number of points. In these cases, this method can also throw TooManyPointsInPatternError or OutOfMemoryError. The situation is like in Pattern.points() and Pattern.roundedPoints() method. However, this situation is possible only in custom implementation of this interface — all implementations, provided by this package, implement either DirectPointSetPattern or RectangularPattern interface.

      There is a guarantee, that if this object implements DirectPointSetPattern interface, then this method requires not greater than O(N) memory (N=pointCount()) and never throws TooManyPointsInPatternError.

      There is a guarantee, that if this object implements RectangularPattern interface, then this method works quickly (O(1) operations) and without exceptions.

      Parameters:
      coordIndex - the index of the coordinate (0 for x, 1 for y, 2 for z, etc.)
      Returns:
      the "upper boundary" of this pattern: new pattern consisting of all points of this pattern, which have no rightward neighbour along the given coordinate.
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=dimCount().
      TooManyPointsInPatternError - (impossible for implementations, provided by this package) if this pattern is not DirectPointSetPattern and not RectangularPattern and if, at the same time, the number of points is greater than Integer.MAX_VALUE or, in some rare situations, is near this limit (OutOfMemoryError can be also thrown instead of this exception).

    • surface

      Pattern surface()
      Returns the set-theoretical union of all patterns, returned by lowerSurface(int) upperSurface(int) methods for all coordinates. In other words, the returned pattern contains full "boundary" of this pattern. The number of dimensions in the resulting pattern (dimCount()) is the same as in this one.

      Note: if this object is not DirectPointSetPattern and is not RectangularPattern, this method can work slowly for some large patterns: the required time can be O(N), where N is the number of points. In these cases, this method can also throw TooManyPointsInPatternError or OutOfMemoryError. The situation is like in Pattern.points() and Pattern.roundedPoints() method. However, this situation is possible only in custom implementation of this interface — all implementations, provided by this package, implement either DirectPointSetPattern or RectangularPattern interface.

      Returns:
      the "boundary" of this pattern: new pattern consisting of all points of this pattern, which have no leftward or rightward neighbour along at least one coordinate.
      Throws:
      TooManyPointsInPatternError - (impossible for implementations, provided by this package) if this pattern is not DirectPointSetPattern and not RectangularPattern and if, at the same time, the number of points is greater than Integer.MAX_VALUE or, in some rare situations, is near this limit (OutOfMemoryError can be also thrown instead of this exception).

    • shift

      UniformGridPattern shift(Point shift)
      Description copied from interface: Pattern
      Returns this pattern, shifted by the argument.

      More precisely, the resulting pattern consists of the points, obtained from all points of this pattern by the call point.add(shift).

      The returned pattern always implements DirectPointSetPattern if this pattern implements DirectPointSetPattern

      The returned pattern always implements RectangularPattern if this pattern implements RectangularPattern.

      The returned pattern always implements UniformGridPattern if this pattern implements UniformGridPattern.

      There is a guarantee, that this method does not try to allocate much more memory, that it is required for storing this pattern itself, and that it never throws TooManyPointsInPatternError. For comparison, an attempt to do the same operation via getting all points (Pattern.points() method), correcting them and forming a new pattern via Patterns.newPattern(java.util.Collection) will lead to TooManyPointsInPatternError / OutOfMemoryError for some forms of large patterns.

      Warning: this method can fail with TooLargePatternCoordinatesException, if some of new points violate restrictions, described in the comments to this interface, section "Coordinate restrictions" (for example, due to very large shift).

      However, TooLargePatternCoordinatesException is impossible in many important cases, when this pattern is an integer pattern and each coordinate Xj=shift.coord(j) of the argument is equal to −xj for some some point (x0, x1, ..., xn−1) of this pattern. In particular, you can use this method for integer patterns without a risk of TooLargePatternCoordinatesException in the following situations:

      See more details in the comments to this interface, section "Coordinate restrictions", the theorem II.

      Specified by:
      shift in interface Pattern
      Parameters:
      shift - the shift.
      Returns:
      the shifted pattern.

    • symmetric

      UniformGridPattern symmetric()
      Description copied from interface: Pattern
      Returns the symmetric pattern: equivalent to multiply(-1.0).

      The returned pattern always implements DirectPointSetPattern if this pattern implements DirectPointSetPattern

      The returned pattern always implements RectangularPattern if this pattern implements RectangularPattern.

      The returned pattern always implements UniformGridPattern if this pattern implements UniformGridPattern.

      There is a guarantee, that this method does not try to allocate much more memory, that it is required for storing this pattern itself, and that it never throws TooManyPointsInPatternError. For comparison, an attempt to do the same operation via getting all points (Pattern.points() method), correcting them and forming a new pattern via Patterns.newPattern(java.util.Collection) will lead to TooManyPointsInPatternError / OutOfMemoryError for some forms of large patterns.

      Specified by:
      symmetric in interface Pattern
      Returns:
      the symmetric pattern.

    • multiply

      UniformGridPattern multiply(double multiplier)
      Description copied from interface: Pattern
      Returns this pattern, scaled by the specified multiplier along all coordinates.

      More precisely, the resulting pattern consists of the points, obtained from all points of this pattern by the call point.multiply(multipliers).

      This method is equivalent to Pattern.scale(double...multipliers), where all Pattern.dimCount() arguments of that method are equal to multiplier.

      The returned pattern always implements DirectPointSetPattern if this pattern implements DirectPointSetPattern

      The returned pattern always implements RectangularPattern if this pattern implements RectangularPattern.

      The returned pattern always implements UniformGridPattern if this pattern implements UniformGridPattern.

      There is a guarantee, that this method does not try to allocate much more memory, that it is required for storing this pattern itself, and that it never throws TooManyPointsInPatternError. For comparison, an attempt to do the same operation via getting all points (Pattern.points() method), correcting them and forming a new pattern via Patterns.newPattern(java.util.Collection) will lead to TooManyPointsInPatternError / OutOfMemoryError for some forms of large patterns.

      Warning: this method can fail with TooLargePatternCoordinatesException, if some of new points violate restrictions, described in the comments to this interface, section "Coordinate restrictions" (for example, due to a very large multiplier). However, such failure is obviously impossible, if the multiplier is in range -1.0<=multiplier<=1.0.

      Specified by:
      multiply in interface Pattern
      Parameters:
      multiplier - the scale along all coordinates.
      Returns:
      the scaled pattern.
      See Also:

    • scale

      UniformGridPattern scale(double... multipliers)
      Description copied from interface: Pattern
      Returns this pattern, scaled by the specified multipliers along all coordinates.

      More precisely, the resulting pattern consists of the points, obtained from all points of this pattern by the call point.scale(multipliers).

      The returned pattern always implements DirectPointSetPattern if this pattern implements DirectPointSetPattern

      The returned pattern always implements RectangularPattern if this pattern implements RectangularPattern.

      The returned pattern always implements UniformGridPattern if this pattern implements UniformGridPattern.

      There is a guarantee, that this method does not try to allocate much more memory, that it is required for storing this pattern itself, and that it never throws TooManyPointsInPatternError. For comparison, an attempt to do the same operation via getting all points (Pattern.points() method), correcting them and forming a new pattern via Patterns.newPattern(java.util.Collection) will lead to TooManyPointsInPatternError / OutOfMemoryError for some forms of large patterns.

      Warning: this method can fail with TooLargePatternCoordinatesException, if some of new points violate restrictions, described in the comments to this interface, section "Coordinate restrictions" (for example, due to very large multipliers). However, such failure is obviously impossible, if all multipliers are in range -1.0<=multipliers[k]<=1.0.

      Specified by:
      scale in interface Pattern
      Parameters:
      multipliers - the scales along coordinates.
      Returns:
      the scaled pattern.
      See Also:

    • projectionAlongAxis

      UniformGridPattern projectionAlongAxis(int coordIndex)
      Description copied from interface: Pattern
      Returns the projection of this pattern along the given axis. The number of dimensions in the resulting pattern (Pattern.dimCount()) is less by 1, than in this one.

      More precisely, the resulting pattern consists of the points, obtained from all points of this pattern by the call point.projectionAlongAxis(coordIndex).

      The returned pattern always implements DirectPointSetPattern if this pattern implements DirectPointSetPattern

      The returned pattern always implements RectangularPattern if this pattern implements RectangularPattern.

      The returned pattern always implements UniformGridPattern if this pattern implements UniformGridPattern.

      There is a guarantee, that this method does not try to allocate much more memory, that it is required for storing this pattern itself, and that it never throws TooManyPointsInPatternError. For comparison, an attempt to do the same operation via getting all points (Pattern.points() method), correcting them and forming a new pattern via Patterns.newPattern(java.util.Collection) will lead to TooManyPointsInPatternError / OutOfMemoryError for some forms of large patterns.

      Specified by:
      projectionAlongAxis in interface Pattern
      Parameters:
      coordIndex - the index of the coordinate (0 for x-axis , 1 for y-axis, 2 for za-xis, etc.).
      Returns:
      the projection of this pattern (its Pattern.dimCount() is equal to thisInstance.Pattern.dimCount()-1).

    • minBound

      UniformGridPattern minBound(int coordIndex)
      Description copied from interface: Pattern
      Returns the minimal boundary of this pattern along the given axis: a pattern consisting of all points of this pattern, for which there are no other points with less coordinate #coordIndex and same other coordinates. The number of dimensions in the resulting pattern (Pattern.dimCount()) is the same as in this one.

      In other words, this method removes some points from this pattern according the following rule: if this pattern contains several points p0, p1, ..., pm−1 with identical projection to the given axis (pi.projectionAlongAxis(coordIndex).equals(pj.projectionAlongAxis(coordIndex)) for all i, j), then the resulting pattern contains only one from these points, for which the given coordinate coord(coordIndex) has the minimal value.

      This method is especially useful for uniform-grid patterns. For example, in rectangular patterns this method returns one of the facets of the hyperparallelepiped. In most cases (including all rectangular patterns) this method returns the same result as lowerSurface(int); but if the figure, described by this pattern, contains some "holes", the result of this method contains fewer points than lowerSurface(int).

      The returned pattern always implements DirectPointSetPattern if this pattern implements DirectPointSetPattern

      The returned pattern always implements RectangularPattern if this pattern implements RectangularPattern.

      The returned pattern always implements UniformGridPattern if this pattern implements UniformGridPattern.

      Warning! If this object is not DirectPointSetPattern and is not RectangularPattern, this method can work slowly for some large patterns: the required time can be O(N), where N is the number of points. In these cases, this method can also throw TooManyPointsInPatternError or OutOfMemoryError. The situation is like in Pattern.points() and Pattern.roundedPoints() method.

      There is a guarantee, that if this object implements DirectPointSetPattern interface, then this method requires not greater than O(N) memory (N=pointCount()) and never throws TooManyPointsInPatternError.

      There is a guarantee, that if this object implements RectangularPattern interface, then this method works quickly (O(1) operations) and without exceptions.

      Specified by:
      minBound in interface Pattern
      Parameters:
      coordIndex - the index of the coordinate (0 for x-axis , 1 for y-axis, 2 for za-xis, etc.).
      Returns:
      the minimal boundary of this pattern for the given axis.
      See Also:

    • maxBound

      UniformGridPattern maxBound(int coordIndex)
      Description copied from interface: Pattern
      Returns the maximal boundary of this pattern along the given axis: a pattern consisting of all points of this pattern, for which there are no other points with greater coordinate #coordIndex and same other coordinates. The number of dimensions in the resulting pattern (Pattern.dimCount()) is the same as in this one.

      In other words, this method removes some points from this pattern according the following rule: if this pattern contains several points p0, p1, ..., pm−1 with identical projection to the given axis (pi.projectionAlongAxis(coordIndex).equals(pj.projectionAlongAxis(coordIndex)) for all i, j), then the resulting pattern contains only one from these points, for which the given coordinate coord(coordIndex) has the maximal value.

      This method is especially useful for uniform-grid patterns. For example, in rectangular patterns this method returns one of the facets of the hyperparallelepiped. In most cases (including all rectangular patterns) this method returns the same result as upperSurface(int); but if the figure, described by this pattern, contains some "holes", the result of this method contains fewer points than upperSurface(int).

      The returned pattern always implements DirectPointSetPattern if this pattern implements DirectPointSetPattern

      The returned pattern always implements RectangularPattern if this pattern implements RectangularPattern.

      The returned pattern always implements UniformGridPattern if this pattern implements UniformGridPattern.

      Warning! If this object is not DirectPointSetPattern and is not RectangularPattern, this method can work slowly for some large patterns: the required time can be O(N), where N is the number of points. In these cases, this method can also throw TooManyPointsInPatternError or OutOfMemoryError. The situation is like in Pattern.points() and Pattern.roundedPoints() method.

      There is a guarantee, that if this object implements DirectPointSetPattern interface, then this method requires not greater than O(N) memory (N=pointCount()) and never throws TooManyPointsInPatternError.

      There is a guarantee, that if this object implements RectangularPattern interface, then this method works quickly (O(1) operations) and without exceptions.

      Specified by:
      maxBound in interface Pattern
      Parameters:
      coordIndex - the index of the coordinate (0 for x-axis , 1 for y-axis, 2 for za-xis, etc.).
      Returns:
      the maximal boundary of this pattern for the given axis.
      See Also:

    • carcass

      UniformGridPattern carcass()
      Description copied from interface: Pattern
      Returns the carcass of this pattern. We define the carcass of the pattern P as such point set C, that, for some integer n>=1:
      1. 2⊗P = P ⊕ C;
        4⊗P = (2⊗P) ⊕ 2C;
        8⊗P = (4⊗P) ⊕ 4C;
        ...
        2n⊗P = (2n−1⊗P) ⊕ 2n−1C;
      2. for any m=1,2,...,n and for any positive integer k≤2m−1, we have
        (2m−1+k)⊗P = (2m−1⊗P) ⊕ kC.

      Here A⊕B means the Minkowski sum of patterns A and B, k⊗P means P⊕P⊕...⊕P (k summands), and kP means the pointwise geometrical multiplication of the pattern P by the multiplier k, i.e. P.multiply(k).

      This method tries to find the minimal carcass, consisting of as little as possible number of points, and the maximal value n, for which the formulas above are correct for the found carcass. (The value 2n is called the maximal carcass multiplier and is returned by Pattern.maxCarcassMultiplier() method.) For example, for rectangular patterns this method returns the set of vertices of the hyperparallelepiped (in one-dimensional case, the pair of segment ends), and the corresponding n=+∞. But this method does not guarantee that the returned result is always the minimal possible carcass and that the found n is really maximal for this carcass.

      This method allows to optimize calculation of the point set of a Minkowski multiple k⊗P. It is really used in the pattern implementations, returned by Patterns.newMinkowskiMultiplePattern(Pattern, int) method: the result of that method is not always an actual Minkowski sum of N equal patterns, but can be (in the best case) an equal Minkowski sum of ~log2N patterns P ⊕ C ⊕ 2C ⊕ ... ⊕ 2mC ⊕ (N−2mC), 2m<N≤2m+1, or (in not the best case, when N is greater than the maximal carcass multiplier 2n) can be another, not so little Minkowski sum.

      In the worst case (no optimization is possible), this method just returns this object (C=P), and Pattern.maxCarcassMultiplier() returns 2 (i.e. n=1).

      The returned pattern has the same number of dimensions (Pattern.dimCount()) as this one.

      The returned pattern always implements UniformGridPattern if this pattern implements UniformGridPattern.

      This method can require some time and memory for execution, but never throws TooManyPointsInPatternError.

      Specified by:
      carcass in interface Pattern
      Returns:
      the carcass of this pattern.