Class AbstractUniformGridPattern

java.lang.Object
net.algart.math.patterns.AbstractPattern
net.algart.math.patterns.AbstractUniformGridPattern
All Implemented Interfaces:
Pattern, UniformGridPattern

public abstract class AbstractUniformGridPattern extends AbstractPattern implements UniformGridPattern

A skeletal implementation of the UniformGridPattern interface to minimize the effort required to implement this interface.

All non-abstract methods are completely implemented here and may be not overridden in subclasses.

Author:
Daniel Alievsky
  • Constructor Details

    • AbstractUniformGridPattern

      protected AbstractUniformGridPattern(Point originOfGrid, double[] stepsOfGrid, boolean trivialUnionDecomposition)
      Creates a uniform grid pattern with the given origin and steps of the grid.

      The trivialUnionDecomposition determines behavior of AbstractPattern.unionDecomposition(int) and allUnionDecompositions(int) methods. If it is false, they will perform some common algorithm suitable for most patterns, that have no good Minkowski decompositions (alike spheres). If it is true, they will return degenerated decomposition consisting of this pattern as the only element. You should use true argument in inheritors that have a good Minkowski decomposition.

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

      Parameters:
      originOfGrid - the origin of the grid.
      stepsOfGrid - the steps of the grid.
      trivialUnionDecomposition - whether this pattern has the degenerated union decomposition.
      Throws:
      NullPointerException - if originOfGrid or stepsOfGrid argument is null.
      IllegalArgumentException - if originOfGrid.coordCount()!=stepsOfGrid.length, or if one of the passed steps is zero (==0.0).
  • Method Details

    • originOfGrid

      public Point originOfGrid()
      This implementation returns the grid origin, specified in the constructor.
      Specified by:
      originOfGrid in interface UniformGridPattern
      Returns:
      the origin o of the uniform grid of this pattern.
    • stepsOfGrid

      public double[] stepsOfGrid()
      This implementation returns a new copy of Java array of grid steps, specified in the constructor.
      Specified by:
      stepsOfGrid in interface UniformGridPattern
      Returns:
      an array containing all grid steps of this pattern.
    • stepOfGrid

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

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

      Specified by:
      stepOfGrid in interface UniformGridPattern
      Returns:
      the grid step of this pattern along the specified coordinate axis.
    • stepsOfGridEqual

      public boolean stepsOfGridEqual(UniformGridPattern pattern)
      Description copied from interface: UniformGridPattern
      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.

      Specified by:
      stepsOfGridEqual in interface 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

      public abstract Set<IPoint> gridIndexes()
      Description copied from interface: UniformGridPattern
      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 UniformGridPattern.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.

      Specified by:
      gridIndexes in interface UniformGridPattern
      Returns:
      all grid indexes of this pattern.
      See Also:
    • gridIndexRange

      public abstract IRange gridIndexRange(int coordIndex)
      Description copied from interface: UniformGridPattern
      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.

      Specified by:
      gridIndexRange in interface UniformGridPattern
      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.
      See Also:
    • gridIndexArea

      public IRectangularArea gridIndexArea()
      This implementation is based on the loop of calls of gridIndexRange(int) method for all coordinate indexes from 0 to AbstractPattern.dimCount()-1.
      Specified by:
      gridIndexArea in interface UniformGridPattern
      Returns:
      the ranges from minimal to maximal coordinate for all space dimensions.
    • gridIndexMin

      public IPoint gridIndexMin()
      This implementation is based on the loop of calls of gridIndexRange(int) method for all coordinate indexes from 0 to AbstractPattern.dimCount()-1.
      Specified by:
      gridIndexMin in interface UniformGridPattern
      Returns:
      minimal grid index for all space dimensions as a point.
    • gridIndexMax

      public IPoint gridIndexMax()
      This implementation is based on the loop of calls of gridIndexRange(int) method for all coordinate indexes from 0 to AbstractPattern.dimCount()-1.
      Specified by:
      gridIndexMax in interface UniformGridPattern
      Returns:
      maximal grid index for all space dimensions as a point.
    • isOrdinary

      public final boolean isOrdinary()
      Description copied from interface: UniformGridPattern
      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 UniformGridPattern.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.

      Specified by:
      isOrdinary in interface UniformGridPattern
      Returns:
      whether the grid origin o=(0,0,...,0) and also all grid steps dj=1.0.
    • isActuallyRectangular

      public boolean isActuallyRectangular()
      This implementation returns true if and only if pointCount()=r0r1...<Long.MAX_VALUE, where ri=gridIndexRange(i).size().

      This method caches its results: the following calls will work faster.

      This method does not provide correct result, if a pattern contains ≥Long.MAX_VALUE points.

      This method should be overridden for rectangular patterns, implementing RectangularPattern interface, or for patterns that surely are not rectangular.

      Specified by:
      isActuallyRectangular in interface UniformGridPattern
      Returns:
      true if this pattern is n-dimensional rectangular parallelepiped.
    • gridIndexPattern

      public abstract UniformGridPattern gridIndexPattern()
      Description copied from interface: UniformGridPattern
      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 UniformGridPattern.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()).

      Specified by:
      gridIndexPattern in interface UniformGridPattern
      Returns:
      an ordinary integer pattern, consisting of all grid indexes of this pattern (represented by double values).
      See Also:
    • shiftGridIndexes

      public abstract UniformGridPattern shiftGridIndexes(IPoint shift)
      Description copied from interface: UniformGridPattern
      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 UniformGridPattern.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 UniformGridPattern.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 UniformGridPattern.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 UniformGridPattern.gridIndexPattern() or UniformGridPattern.gridIndexes() method.

      Specified by:
      shiftGridIndexes in interface UniformGridPattern
      Parameters:
      shift - the shift of the grid indexes.
      Returns:
      the shifted pattern.
    • lowerSurface

      public UniformGridPattern lowerSurface(int coordIndex)
      Description copied from interface: UniformGridPattern
      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, ..., xjdj, ..., xn−1) (corresponding to decreasing the grid index ij by 1) does not belong to this pattern.

      Please compare with UniformGridPattern.minBound(int) method. This method can return a pattern containing more points than UniformGridPattern.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.

      Specified by:
      lowerSurface in interface UniformGridPattern
      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.
    • upperSurface

      public UniformGridPattern upperSurface(int coordIndex)
      Description copied from interface: UniformGridPattern
      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 UniformGridPattern.maxBound(int) method. This method can return a pattern containing more points than UniformGridPattern.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.

      Specified by:
      upperSurface in interface UniformGridPattern
      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.
    • surface

      public Pattern surface()
      Description copied from interface: UniformGridPattern
      Returns the set-theoretical union of all patterns, returned by UniformGridPattern.lowerSurface(int) UniformGridPattern.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.

      Specified by:
      surface in interface UniformGridPattern
      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.
    • pointCount

      public abstract long pointCount()
      Description copied from interface: Pattern
      Returns the number of points in this pattern. This value is always positive (>=1). If the number of points is greater than Long.MAX_VALUE, returns Long.MAX_VALUE.

      Warning! This method can work slowly for some forms of large patterns: the required time can be O(N), where N is the number of points (result of this method). In these cases, this method can also throw TooManyPointsInPatternError or OutOfMemoryError.

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

      There is a guarantee, that if this object implements DirectPointSetPattern interface, then the result of this method is not greater than Integer.MAX_VALUE.

      Note: if this method returns some value greater than Integer.MAX_VALUE, it means that you cannot use Pattern.points() and Pattern.roundedPoints() methods, because Java Set object cannot contain more than Integer.MAX_VALUE elements.

      Specified by:
      pointCount in interface Pattern
      Specified by:
      pointCount in class AbstractPattern
      Returns:
      the number of points in this pattern.
      See Also:
    • points

      public Set<Point> points()
      Description copied from interface: Pattern
      Returns a set of all points of this pattern.

      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 this 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: this method works very quickly (O(1) operations) in SimplePattern class.

      Specified by:
      points in interface Pattern
      Specified by:
      points in class AbstractPattern
      Returns:
      all points of this pattern.
    • roundedPoints

      public Set<IPoint> roundedPoints()
      Description copied from class: AbstractPattern
      This implementation calls AbstractPattern.points() method and returns a new set, built from the returned set of real points by conversion of every point to an integer point via Point.toRoundedPoint() method, as written in comments to this method in Pattern interface. Please override this method if there is more efficient way to get all rounded points.
      Specified by:
      roundedPoints in interface Pattern
      Overrides:
      roundedPoints in class AbstractPattern
      Returns:
      all points of this pattern, rounded to the nearest integer points.
    • coordRange

      public Range coordRange(int coordIndex)
      Description copied from interface: Pattern
      Returns the minimal and maximal coordinate with the given index (Point.coord(coordIndex)) among all points of this pattern. The minimal coordinate will be r.min(), the maximal coordinate will be r.max(), where r is the result of this method.

      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.

      Specified by:
      coordRange in interface Pattern
      Specified by:
      coordRange in class AbstractPattern
      Parameters:
      coordIndex - the index of the coordinate (0 for x, 1 for y, 2 for z, etc.).
      Returns:
      the range from minimal to maximal coordinate with this index.
      See Also:
    • isSurelyInteger

      public boolean isSurelyInteger()
      Description copied from class: AbstractPattern
      This implementation calls AbstractPattern.points() method and checks, whether all returned points are integer, i.e. Point.isInteger() method returns true for all elements the returned set. If all points, returned by AbstractPattern.points() call, are integer, this method returns true, in other case it returns false.

      This method caches its results: the following calls will work faster.

      Note: according the comments to this method in Pattern interface, such implementation is correct only if AbstractPattern.minkowskiDecomposition(int), AbstractPattern.unionDecomposition(int) and AbstractPattern.allUnionDecompositions(int) methods have default implementations (not overridden). If some of them are overridden and return some non-trivial results, this method must be also overridden.

      Note: according the comments to this method in Pattern interface, this method must be overridden if the number of points can be very large and a call of AbstractPattern.points() method leads to a risk of TooManyPointsInPatternError / OutOfMemoryError. In particular, this method should be usually overridden in implementations of RectangularPattern.

      Specified by:
      isSurelyInteger in interface Pattern
      Overrides:
      isSurelyInteger in class AbstractPattern
      Returns:
      true if this pattern assuredly contain only integer points.
    • round

      public UniformGridPattern round()
      Description copied from class: AbstractPattern
      This implementation calls AbstractPattern.roundedPoints() method and constructs a new integer pattern on the base of this set, like as it is performed in Patterns.newIntegerPattern(java.util.Collection) method. Please override this method if there is more efficient way to round this pattern, for example, if this pattern is already an integer one.
      Specified by:
      round in interface Pattern
      Overrides:
      round in class AbstractPattern
      Returns:
      the integer pattern, geometrically nearest to this one.
    • projectionAlongAxis

      public abstract 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
      Specified by:
      projectionAlongAxis in interface UniformGridPattern
      Specified by:
      projectionAlongAxis in class AbstractPattern
      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

      public UniformGridPattern minBound(int coordIndex)
      Description copied from class: AbstractPattern
      This implementation calls AbstractPattern.points() method and builds the result on the base of analysis of the returned point set. Please override this method if there is more efficient way to find the result, for example, if this pattern is a rectangular one.
      Specified by:
      minBound in interface Pattern
      Specified by:
      minBound in interface UniformGridPattern
      Overrides:
      minBound in class AbstractPattern
      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

      public UniformGridPattern maxBound(int coordIndex)
      Description copied from class: AbstractPattern
      This implementation calls AbstractPattern.points() method and builds the result on the base of analysis of the returned point set. Please override this method if there is more efficient way to find the result, for example, if this pattern is a rectangular one.
      Specified by:
      maxBound in interface Pattern
      Specified by:
      maxBound in interface UniformGridPattern
      Overrides:
      maxBound in class AbstractPattern
      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

      public UniformGridPattern carcass()
      //TODO!! - that it checks isActuallyRectangular() This method is fully implemented in this class and usually should not be overridden. If you override it, you must override maxCarcassMultiplier() also, because that method returns the private field calculated by this one.
      Specified by:
      carcass in interface Pattern
      Specified by:
      carcass in interface UniformGridPattern
      Overrides:
      carcass in class AbstractPattern
      Returns:
      the carcass of this pattern.
    • maxCarcassMultiplier

      public int maxCarcassMultiplier()
      //TODO!! - write that it checks isActuallyRectangular() This method is fully implemented in this class and usually should not be overridden.
      Specified by:
      maxCarcassMultiplier in interface Pattern
      Overrides:
      maxCarcassMultiplier in class AbstractPattern
      Returns:
      the maximal multiplier, for which the calculation of the Minkowski multiple can be optimized by using the carcass.
    • shift

      public abstract 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
      Specified by:
      shift in interface UniformGridPattern
      Specified by:
      shift in class AbstractPattern
      Parameters:
      shift - the shift.
      Returns:
      the shifted pattern.
    • symmetric

      public UniformGridPattern symmetric()
      Description copied from class: AbstractPattern
      This implementation calls multiply(-1.0). There are no reasons to override this method usually.
      Specified by:
      symmetric in interface Pattern
      Specified by:
      symmetric in interface UniformGridPattern
      Overrides:
      symmetric in class AbstractPattern
      Returns:
      the symmetric pattern.
    • multiply

      public UniformGridPattern multiply(double multiplier)
      Description copied from class: AbstractPattern
      This implementation creates Java array double[] by the call "a = new double[AbstractPattern.dimCount]", fills all its elements by multiplier argument and then calls scale(a). There are no reasons to override this method usually.
      Specified by:
      multiply in interface Pattern
      Specified by:
      multiply in interface UniformGridPattern
      Overrides:
      multiply in class AbstractPattern
      Parameters:
      multiplier - the scale along all coordinates.
      Returns:
      the scaled pattern.
      See Also:
    • scale

      public abstract 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
      Specified by:
      scale in interface UniformGridPattern
      Specified by:
      scale in class AbstractPattern
      Parameters:
      multipliers - the scales along coordinates.
      Returns:
      the scaled pattern.
      See Also:
    • minkowskiAdd

      public Pattern minkowskiAdd(Pattern added)
      This implementation is based on the loop on all points returned by roundedPoints() method in both patterns and always returns the simple pattern consisting of sums of all point pairs. This algorithm may be very slow for large patterns (O(NM) operations, N=pointCount(), M=added.pointCount()) and does not work at all if the number of resulting points is greater than Integer.MAX_VALUE. Please override this method if there is better implementation.
      Specified by:
      minkowskiAdd in interface Pattern
      Overrides:
      minkowskiAdd in class AbstractPattern
      Parameters:
      added - another pattern.
      Returns:
      the Minkowski sum of this and another patterns.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if the numbers of space dimensions of both patterns are different.
      See Also:
    • minkowskiSubtract

      public Pattern minkowskiSubtract(Pattern subtracted)
      This implementation is based on the loop on all points returned by roundedPoints() method in both patterns and always returns the simple pattern consisting of sums of all point pairs. This algorithm may be very slow for large patterns (O(NM) operations, N=pointCount(), M=added.pointCount()) and does not work at all if the number of resulting points is greater than Integer.MAX_VALUE. Please override this method if there is better implementation.
      Specified by:
      minkowskiSubtract in interface Pattern
      Overrides:
      minkowskiSubtract in class AbstractPattern
      Parameters:
      subtracted - another pattern.
      Returns:
      the erosion of this pattern by the specified pattern or null if this erosion is the empty set.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if the numbers of space dimensions of both patterns are different.
      See Also:
    • minkowskiDecomposition

      public List<Pattern> minkowskiDecomposition(int minimalPointCount)
      This implementation returns Collections.<Pattern>singletonList(thisInstance) for non-rectangular patterns or a good decomposition if isActuallyRectangular() method returns true. This method caches its results for several little values of the argument: the following calls will work faster. Please override this method if there is better implementation.
      Specified by:
      minkowskiDecomposition in interface Pattern
      Overrides:
      minkowskiDecomposition in class AbstractPattern
      Parameters:
      minimalPointCount - this method does not try to decompose patterns that contain less than minimalPointCount points. In particular, if the minkowski sum of several patterns containing less than minimalPointCount points, this method should return this sum in the resulting list instead of its summands.
      Returns:
      the decomposition of this pattern to Minkowski sum.
      Throws:
      IllegalArgumentException - if the argument is negative.
    • hasMinkowskiDecomposition

      public boolean hasMinkowskiDecomposition()
      This implementation returns minkowskiDecomposition(0).size()>1. Please override this method if minkowskiDecomposition(int) method works slowly and it's possible to know, whether the pattern has Minkowski decomposition, much faster.
      Specified by:
      hasMinkowskiDecomposition in interface Pattern
      Overrides:
      hasMinkowskiDecomposition in class AbstractPattern
      Returns:
      true if the Minkowski decomposition contains 2 or more elements.
    • allUnionDecompositions

      public List<List<Pattern>> allUnionDecompositions(int minimalPointCount)
      This implementation uses a common algorithm that usually provide good results. This method caches its results for several little values of the argument: the following calls will work faster. Please override this method if the better implementation is known.
      Specified by:
      allUnionDecompositions in interface Pattern
      Overrides:
      allUnionDecompositions in class AbstractPattern
      Parameters:
      minimalPointCount - the minimal number of points in every pattern in all resulting decompositions: all pattern containing less points should be joined into one element of the resulting list.
      Returns:
      several good variants of decomposition of this pattern to the union of patterns.
      Throws:
      IllegalArgumentException - if the argument is negative.
    • isAllowedGridIndex

      public static boolean isAllowedGridIndex(IPoint gridIndex)
    • isAllowedGridIndexRange

      public static boolean isAllowedGridIndexRange(IRange gridIndexRange)
    • gridToString

      protected String gridToString()