Package net.algart.math.patterns

Class AbstractWeightedPattern

java.lang.Object
net.algart.math.patterns.AbstractWeightedPattern
All Implemented Interfaces:
Pattern, WeightedPattern
public abstract class AbstractWeightedPattern extends Object implements WeightedPattern

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

This implementation is based on using some "parent" pattern, implementing Pattern interface and passed to the constructor. All methods of this class, excepting declared in the WeightedPattern interface, just call the same methods of the parent pattern. To complete implementation, you just need to implement several methods from the WeightedPattern interface.

Author:
Daniel Alievsky

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected final Pattern
    parent
    The parent pattern.

    Fields inherited from interface net.algart.math.patterns.Pattern

    MAX_COORDINATE

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    AbstractWeightedPattern(Pattern parent)
    Creates a new weighted pattern on the base of the given parent one.

  • Method Summary

    Modifier and Type
    Method
    Description
    List<List<Pattern>>
    allUnionDecompositions(int minimalPointCount)
    Returns a non-empty list of all best or almost best union decompositions with equal or similar "quality", i.e. with the same or almost same summary number of points in all Minkowski decompositions of all returned patterns.
    Pattern
    carcass()
    Returns the carcass of this pattern.
    RectangularArea
    coordArea()
    Returns the minimal and maximal coordinates among all points of this pattern for all dimensions.
    Point
    coordMax()
    Returns the point, each coordinate of which is equal to the maximal corresponding coordinate among all points of this pattern.
    Point
    coordMin()
    Returns the point, each coordinate of which is equal to the minimal corresponding coordinate among all points of this pattern.
    Range
    coordRange(int coordIndex)
    Returns the minimal and maximal coordinate with the given index (Point.coord(coordIndex)) among all points of this pattern.
    int
    dimCount()
    Returns the number of space dimensions of this pattern.
    boolean
    hasMinkowskiDecomposition()
    Returns true if and only if the Minkowski decomposition, returned by minkowskiDecomposition(0) call, consists of 2 or more patterns: minkowskiDecomposition(0).size()>1.
    boolean
    isConstant()
    This implementation returns weightRange().size()==0.0.
    boolean
    isSurelyInteger()
    Returns true if this pattern is integer: all coordinates of all points of this pattern are integer numbers.
    boolean
    isSurelyOriginPoint()
    Returns true if this pattern consists of the single point and this point is the origin of coordinates.
    boolean
    isSurelySinglePoint()
    Returns true if this pattern consists of the single point, i.e. if pointCount()==1.
    double
    largePointCount()
    Returns the number of points in this pattern as double value.
    Pattern
    maxBound(int coordIndex)
    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.
    int
    maxCarcassMultiplier()
    Returns the maximal multiplier k, for which the calculation of the Minkowski multiple k⊗P can be optimized by using the carcass of this pattern P.
    Pattern
    minBound(int coordIndex)
    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.
    Pattern
    minkowskiAdd(Pattern added)
    Calculates and returns the Minkowski sum of this and specified patterns.
    List<Pattern>
    minkowskiDecomposition(int minimalPointCount)
    Returns the Minkowski decomposition: a non-empty list of patterns P0, P1, ..., Pn−1, such that this pattern P (the point set represented by it) is a Minkowski sum of them (of the point sets represented by them): P = P0 ⊕ P1 ⊕...⊕ Pn−1.
    Pattern
    minkowskiSubtract(Pattern subtracted)
    Calculates and returns the erosion of this pattern by specified pattern or null if this erosion is the empty set.
    WeightedPattern
    multiply(double multiplier)
    Returns the pattern consisting of points, generated from points of this instance by multiplying on the mult argument via IPoint.multiply(double) method.
    long
    pointCount()
    Returns the number of points in this pattern.
    Set<Point>
    points()
    Returns a set of all points of this pattern.
    List<WeightedPattern>
    productDecomposition(int minimalPointCount)
    This implementation returns Collections.singletonList(this).
    Pattern
    projectionAlongAxis(int coordIndex)
    Returns the projection of this pattern along the given axis.
    UniformGridPattern
    round()
    Returns this pattern, every point of which is rounded to the nearest integer point.
    IRectangularArea
    roundedCoordArea()
    Returns the same result as Pattern.coordArea() method, but all minimal and maximal coordinates are rounded to integer values by StrictMath.round operation.
    IRange
    roundedCoordRange(int coordIndex)
    Returns the same result as Pattern.coordRange(int coordIndex) method, but both minimal and maximal coordinates are rounded to integer values by StrictMath.round operation.
    Set<IPoint>
    roundedPoints()
    Returns the set of all integer points, obtained from the points of this pattern (results of points() method by rounding with help of Point.toRoundedPoint() method.
    abstract WeightedPattern
    scale(double... multipliers)
    Returns this pattern, scaled by the specified multipliers along all coordinates.
    abstract WeightedPattern
    shift(IPoint shift)
    Returns the pattern shifted by the argument, that is consisting of points with the same weights, generated from points of this instance by adding the argument via IPoint.add(IPoint) method.
    WeightedPattern
    shift(Point shift)
    Returns this pattern, shifted by the argument.
    WeightedPattern
    symmetric()
    This implementation calls multiply(-1.0).
    List<Pattern>
    unionDecomposition(int minimalPointCount)
    Returns a union decomposition: a non-empty list of patterns P0, P1, ..., Pn−1, such that this pattern P (the point set represented by it) is the set-theoretical union of them (of the point sets represented by them): P = P0 ∪ P1 ∪...∪ Pn−1.
    abstract double
    weight(IPoint point)
    Returns the weight of the given point of the pattern.
    abstract Range
    weightRange()
    Returns the minimal and maximal weights of all points of this pattern.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • parent

      protected final Pattern parent
      The parent pattern.

  • Constructor Details

    • AbstractWeightedPattern

      protected AbstractWeightedPattern(Pattern parent)
      Creates a new weighted pattern on the base of the given parent one.
      Parameters:
      parent - the parent pattern, serving most of all methods of this instance.
      Throws:
      NullPointerException - if the argument is null.

  • Method Details

    • dimCount

      public int dimCount()
      Description copied from interface: Pattern
      Returns the number of space dimensions of this pattern. This value is always positive (>=1).

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

      Specified by:
      dimCount in interface Pattern
      Returns:
      the number of space dimensions of this pattern.

    • pointCount

      public 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
      Returns:
      the number of points in this pattern.
      See Also:

    • largePointCount

      public double largePointCount()
      Description copied from interface: Pattern
      Returns the number of points in this pattern as double value. In particular, if the result of Pattern.pointCount() method is not greater than Long.MAX_VALUE, there is a guarantee that this method returns the same result, cast to double type.

      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.

      Specified by:
      largePointCount in interface Pattern
      Returns:
      the number of points in this pattern as double value.
      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
      Returns:
      all points of this pattern.

    • roundedPoints

      public Set<IPoint> roundedPoints()
      Description copied from interface: Pattern

      Returns the set of all integer points, obtained from the points of this pattern (results of points() method by rounding with help of Point.toRoundedPoint() method. In other words, the results of this method is the same as the result of the following code: 

           Set<IPoint> result = new HashSet<IPoint>(); // or another Set implementation
     for (Point p : points()) {
         result.add(p.toRoundedPoint());
     }
     result = Collections.unmodifiableSet(result);

      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.

      Note: the number of resulting points can be less than Pattern.pointCount(), because some real points can be rounded to the same integer points.

      According the basic restriction to pattern coordinates (see the comments to this interface, section "Coordinate restrictions"), you may be sure that you will able to create an integer uniform-grid pattern by passing the result of this method to Patterns.newIntegerPattern(java.util.Collection).

      Warning! This method can work slowly or throw TooManyPointsInPatternError / OutOfMemoryError in the same situations as Pattern.points() method.

      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. Please compare with Pattern.round() method, which always works quickly and without exceptions also for the case of RectangularPattern.

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

    • coordArea

      public RectangularArea coordArea()
      Description copied from interface: Pattern
      Returns the minimal and maximal coordinates among all points of this pattern for all dimensions. If a is the result of this method, then a.coordCount()==dimCount() and a.range(k) is equal to coordRange(k) for all k.

      For example, in 2-dimensional case the result is the circumscribed rectangle (with sides, parallel to the axes).

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

      Specified by:
      coordArea in interface Pattern
      Returns:
      the ranges from minimal to maximal coordinate for all space dimensions.
      See Also:

    • coordMin

      public Point coordMin()
      Description copied from interface: Pattern
      Returns the point, each coordinate of which is equal to the minimal corresponding coordinate among all points of this pattern. Equivalent to Pattern.coordArea().min().

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

      Specified by:
      coordMin in interface Pattern
      Returns:
      minimal coordinates for all space dimensions as a point.

    • coordMax

      public Point coordMax()
      Description copied from interface: Pattern
      Returns the point, each coordinate of which is equal to the maximal corresponding coordinate among all points of this pattern. Equivalent to Pattern.coordArea().max().

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

      Specified by:
      coordMax in interface Pattern
      Returns:
      maximal coordinates for all space dimensions as a point.

    • roundedCoordRange

      public IRange roundedCoordRange(int coordIndex)
      Description copied from interface: Pattern
      Returns the same result as Pattern.coordRange(int coordIndex) method, but both minimal and maximal coordinates are rounded to integer values by StrictMath.round operation. Equivalent to coordRange(coordIndex).toRoundedRange().

      According the basic restriction to pattern coordinates (see the comments to this interface, section "Coordinate restrictions"), you may be sure that you will be able to create an integer rectangular pattern by passing the ranges, got by this method, to Patterns.newRectangularIntegerPattern(IRange...).

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

      Specified by:
      roundedCoordRange in interface Pattern
      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, rounded to the long values.
      See Also:

    • roundedCoordArea

      public IRectangularArea roundedCoordArea()
      Description copied from interface: Pattern
      Returns the same result as Pattern.coordArea() method, but all minimal and maximal coordinates are rounded to integer values by StrictMath.round operation. The method IRectangularArea.range(int coordIndex) in the returned area returns the same result as Pattern.roundedCoordRange(int coordIndex) method in this object.

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

      Specified by:
      roundedCoordArea in interface Pattern
      Returns:
      the ranges from minimal to maximal coordinate for all space dimensions, rounded to the long values.

    • isSurelySinglePoint

      public boolean isSurelySinglePoint()
      Description copied from interface: Pattern
      Returns true if this pattern consists of the single point, i.e. if pointCount()==1.

      There are no strict guarantees that this method always returns true if the pattern consist of the single point. (In some complex situations, such analysis can be too difficult. In particular, if the pattern is a Minkowski sum, then limited floating-point precision can lead to equality of all points of the result. Simple example: a Minkowski sum of two-point one-dimensional pattern, consisting of points 0.0 and 0.000001, and one-point 251=2251799813685248.0, contains only 1 point 251, because the computer cannot represent precise value 2251799813685248.000001 in double type and rounds it to 2251799813685248.0. In such situations, this method sometimes may incorrectly return false.)

      But there is the reverse guarantee: if this method returns true, the number of points in this pattern is always 1.

      Unlike Pattern.pointCount() method, there is a guarantee that this method never works very slowly and cannot lead to TooManyPointsInPatternError / OutOfMemoryError. In situations, when the number of points is very large (and, so, Pattern.pointCount() method is not safe in use), this method must detect this fact in reasonable time and return false.

      There is a guarantee, that if this object implements QuickPointCountPattern interface, then this method works very quickly (O(1) operations) and absolutely correctly (always returns true if and only if pointCount()==1).

      Specified by:
      isSurelySinglePoint in interface Pattern
      Returns:
      true if it is one-point pattern.
      See Also:

    • isSurelyOriginPoint

      public boolean isSurelyOriginPoint()
      Description copied from interface: Pattern
      Returns true if this pattern consists of the single point and this point is the origin of coordinates.

      There are no strict guarantees that this method always returns true if the pattern consist of the single point, equal to the origin of coordinates. (In some complex situations, such analysis can be too difficult. In such situations, this method may incorrectly return false.) But there is the reverse guarantee: if this method returns true, the number of points in this pattern is always 1 and its only point is the origin of coordinates, in terms of Point.isOrigin() method.

      Unlike Pattern.pointCount() method, there is a guarantee that this method never works very slowly and cannot lead to TooManyPointsInPatternError / OutOfMemoryError. In situations, when the number of points is very large (and, so, Pattern.pointCount() method is not safe in use), this method must detect this fact in reasonable time and return false.

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

      Specified by:
      isSurelyOriginPoint in interface Pattern
      Returns:
      true if it is one-point pattern containing the origin of coordinates as the single point.
      See Also:

    • projectionAlongAxis

      public Pattern 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).

    • isSurelyInteger

      public boolean isSurelyInteger()
      Description copied from interface: Pattern
      Returns true if this pattern is integer: all coordinates of all points of this pattern are integer numbers. In other words, it means that for each real (double) coordinate x of each point of this pattern the Java expression x==(long)x is true.

      More precisely, if this method returns true, then there are the following guarantees:

      1. for each point, returned by Pattern.points() method, as well as by Pattern.coordMin()/Pattern.coordMax(), Point.isInteger() method returns true;
      2. each pattern, returned in the results of Pattern.minkowskiDecomposition(int), Pattern.unionDecomposition(int) and Pattern.allUnionDecompositions(int) methods, is also surely integer, i.e. this method also returns true for it.

      However, there are no strict guarantees that this method always returns true if the pattern is really integer. In other words, if this method returns false, there is no guarantee, that this pattern really contains some non-integer points — but it is probable.

      Unlike Pattern.points() method, there is a guarantee that this method never works very slowly and cannot lead to TooManyPointsInPatternError / OutOfMemoryError. In situations, when the number of points is very large and there is a risk to fail with TooManyPointsInPatternError / OutOfMemoryError, this method must detect this fact in reasonable time and return false.

      See the comments to this interface, section "Integer patterns", for more details.

      Specified by:
      isSurelyInteger in interface Pattern
      Returns:
      true if this pattern and all patterns of its decomposition (Minkowski or union) assuredly contain only integer points.

    • round

      public UniformGridPattern round()
      Description copied from interface: Pattern
      Returns this pattern, every point of which is rounded to the nearest integer point. The result is always ordinary integer pattern (see the comments to this interface, section "Uniform-grid patterns").

      More precisely, the resulting pattern:

      1. consists of all points, obtained from all points of this pattern by rounding by the call point.toRoundedPoint().toPoint();
      2. has zero origin UniformGridPattern.originOfGrid()=(0,0,...,0) and unit steps UniformGridPattern.stepsOfGrid()={1,1,..,1}.

      Note: the number of points in the result can be less than Pattern.pointCount(), because some real points can be rounded to the same integer points.

      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) operations and 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. It is an important difference from Pattern.points() and Pattern.roundedPoints() method.

      The theorem I, described in the comments to this interface, section "Coordinate restrictions", provides a guarantee that this method never throws TooLargePatternCoordinatesException.

      Specified by:
      round in interface Pattern
      Returns:
      the integer pattern, geometrically nearest to this one.

    • minBound

      public Pattern 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 UniformGridPattern.lowerSurface(int); but if the figure, described by this pattern, contains some "holes", the result of this method contains fewer points than UniformGridPattern.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

      public Pattern 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 UniformGridPattern.upperSurface(int); but if the figure, described by this pattern, contains some "holes", the result of this method contains fewer points than UniformGridPattern.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

      public Pattern 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.

    • maxCarcassMultiplier

      public int maxCarcassMultiplier()
      Description copied from interface: Pattern
      Returns the maximal multiplier k, for which the calculation of the Minkowski multiple k⊗P can be optimized by using the carcass of this pattern P. Please see Pattern.carcass() method for more information.

      Note: the returned value is always ≥2. If the correct value is greater than Integer.MAX_VALUE (for example, for rectangular patterns), this method returns Integer.MAX_VALUE; in all other cases the returning value is a power of two.

      This method can require some time and memory for execution, but never throws TooManyPointsInPatternError. Usually an implementation caches the results of Pattern.carcass() and this methods, so this method works very quickly after the first call of Pattern.carcass().

      Specified by:
      maxCarcassMultiplier in interface Pattern
      Returns:
      the maximal multiplier (≥2), for which the calculation of the Minkowski multiple can be optimized by using the carcass.

    • minkowskiAdd

      public Pattern minkowskiAdd(Pattern added)
      Description copied from interface: Pattern
      Calculates and returns the Minkowski sum of this and specified patterns. Briefly, the returned pattern consists of all points a+b, where a is any point of this pattern, b is any point of the argument "added" and "+" means a vector sum of two points (the result of "a.add(b)" call). Please see details in Wikipedia.

      Warning! This method can work slowly for some forms of large patterns. In these cases, this method can also throw TooManyPointsInPatternError or OutOfMemoryError.

      Warning: this method can fail with TooLargePatternCoordinatesException, if some of new points violate restrictions, described in the comments to this interface, section "Coordinate restrictions".

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

      The returned pattern always implements RectangularPattern if this pattern and subtracted argument implement RectangularPattern and both patterns have identical steps (i.e. thisPattern.stepsOfGridEqual(subtracted) returns true). In this case, this method works very quickly and without TooManyPointsInPatternError / OutOfMemoryError exceptions.

      Please draw attention: there is another way to build a Minkowski sum, namely the method Patterns.newMinkowskiSum(java.util.Collection). That method does not perform actual calculations and returns a special implementation of this interface (see comments to this interface, section "Complex patterns"). Unlike that method, this one tries to actually calculate the Minkowski sum, saving (when possible) the type of the original pattern: see above two guarantees about DirectPointSetPattern and RectangularPattern types. If it is impossible to represent the Minkowski sum by Java class of this pattern, it is probable that the result will be constructed as DirectPointSetUniformGridPattern or as SimplePattern.

      Specified by:
      minkowskiAdd in interface Pattern
      Parameters:
      added - another pattern.
      Returns:
      the Minkowski sum of this and another patterns.
      See Also:

    • minkowskiSubtract

      public Pattern minkowskiSubtract(Pattern subtracted)
      Description copied from interface: Pattern
      Calculates and returns the erosion of this pattern by specified pattern or null if this erosion is the empty set. Briefly, the returned pattern consists of all such points p, that for any points b of the "subtracted" pattern the vector sum of two points p+b (the result of "p.add(b)" call) belongs to this pattern. Please see more details in Wikipedia and Google about the "Erosion" and "Minkowski subtraction" terms.

      Warning! This method can work slowly for some forms of large patterns. In these cases, this method can also throw TooManyPointsInPatternError or OutOfMemoryError.

      Warning: this method can fail with TooLargePatternCoordinatesException, if some of new points violate restrictions, described in the comments to this interface, section "Coordinate restrictions". But it is obvious, that this exception is impossible if the passed pattern "subtracted" contains the origin of coordinates (in this case, the result is a subset of this pattern).

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

      The returned pattern always implements RectangularPattern if this pattern and subtracted argument implement RectangularPattern and both patterns have identical steps (i.e. thisPattern.stepsOfGridEqual(subtracted) returns true). In this case, this method works very quickly and without TooManyPointsInPatternError / OutOfMemoryError exceptions.

      Specified by:
      minkowskiSubtract in interface Pattern
      Parameters:
      subtracted - another pattern.
      Returns:
      the erosion of this pattern by the specified pattern or null if this erosion is the empty set.
      See Also:

    • minkowskiDecomposition

      public List<Pattern> minkowskiDecomposition(int minimalPointCount)
      Description copied from interface: Pattern
      Returns the Minkowski decomposition: a non-empty list of patterns P0, P1, ..., Pn−1, such that this pattern P (the point set represented by it) is a Minkowski sum of them (of the point sets represented by them): P = P0 ⊕ P1 ⊕...⊕ Pn−1. In other words, each point p∈P of this pattern is equal to a vector sum of some n points p0, p1, ..., pn−1, where pi∈Pi. Please see Wikipedia about the "Minkowski sum" term.

      This method tries to find the best decomposition, that means the list of patterns with minimal summary number of points. For good pattern, the returned patterns list can consist of O(log2N) points (sum of Pattern.pointCount() values for all returned patterns), where N is the number of points (Pattern.pointCount()) in this pattern. For example, a linear one-dimensional segment {x: 0<=x<2m} is a Minkowski sum of m point pairs {0, 2i}, i=0,1,...,m-1.

      There is no guarantee that this method returns a good decomposition. If this method cannot find required decomposition, it returns the 1-element list containing this instance as the only element.

      If the number of points in this pattern is less than the argument, i.e. Pattern.pointCount()<minimalPointCount, then this method probably does not decompose this pattern and returns the 1-element list containing this instance as its element. But it is not guaranteed: if the method "knows" some decomposition, but estimation of the number of points can require a lot of resources, this method may ignore minimalPointCount argument.

      However, there is a guarantee that if the number of points is 1 or 2, i.e. Pattern.pointCount()≤2, then this method always returns the 1-element list containing this instance as its element.

      There is a guarantee that the elements of the resulting list cannot be further decomposed: this method, called for them with the same or larger minimalPointCount argument, always returns a list consisting of one element.

      The number of space dimensions in all returned patterns (Pattern.dimCount() is the same as in this one.

      The result of this method is immutable (Collections.unmodifiableList).

      Specified by:
      minkowskiDecomposition in interface Pattern
      Parameters:
      minimalPointCount - this method usually does not decompose patterns that contain less than minimalPointCount points.
      Returns:
      the decomposition of this pattern to Minkowski sum; always contains ≥1 elements.

    • hasMinkowskiDecomposition

      public boolean hasMinkowskiDecomposition()
      Description copied from interface: Pattern
      Returns true if and only if the Minkowski decomposition, returned by minkowskiDecomposition(0) call, consists of 2 or more patterns: minkowskiDecomposition(0).size()>1.

      In some situations this method works essentially faster then the actual minkowskiDecomposition(0) call.

      Note that if this method returns true, then Pattern.pointCount() and Pattern.largePointCount() methods can work very slowly and even may fail with OutOfMemoryError or TooManyPointsInPatternError.

      Specified by:
      hasMinkowskiDecomposition in interface Pattern
      Returns:
      true if the Minkowski decomposition contains 2 or more elements.

    • unionDecomposition

      public List<Pattern> unionDecomposition(int minimalPointCount)
      Description copied from interface: Pattern
      Returns a union decomposition: a non-empty list of patterns P0, P1, ..., Pn−1, such that this pattern P (the point set represented by it) is the set-theoretical union of them (of the point sets represented by them): P = P0 ∪ P1 ∪...∪ Pn−1.

      This method tries to find such decomposition, that all patterns Pi have good Minkowski decompositions and the summary number of points in all Minkowski decompositions Pi.minkowskiDecomposition(minimalPointCount) of all patterns, returned by this method, is as small as possible — usually much less than the number of points in this instance. If this pattern already has a good Minkowski decompositions, this method should return the 1-element list containing this instance as the only element.

      If the number of points in this pattern is less than the argument, i.e. Pattern.pointCount()<minimalPointCount, then this method probably does not decompose this pattern and returns the 1-element list containing this instance as its element. Moreover, this method tries to build such decomposition, that every element Pi in the resulting list contains ≥minimalPointCount elements.

      There is a guarantee that the elements of the resulting list cannot be further decomposed: this method, called for them with the same or larger minimalPointCount argument, always returns a list consisting of one element.

      The number of space dimensions in all returned patterns (Pattern.dimCount() is the same as in this one.

      The result of this method is immutable (Collections.unmodifiableList).

      Specified by:
      unionDecomposition in interface Pattern
      Parameters:
      minimalPointCount - this method usually does not decompose patterns that contain less than minimalPointCount points.
      Returns:
      a decomposition of this pattern into the union of patterns; always contains ≥1 elements.

    • allUnionDecompositions

      public List<List<Pattern>> allUnionDecompositions(int minimalPointCount)
      Description copied from interface: Pattern
      Returns a non-empty list of all best or almost best union decompositions with equal or similar "quality", i.e. with the same or almost same summary number of points in all Minkowski decompositions of all returned patterns.

      This method is a useful addition to Pattern.unionDecomposition(int) method for a case, when there are several union decompositions with similar "quality". In this case an algorithm, using union decompositions, is able to choose the best from several variants according additional algorithm-specific criteria.

      The number of space dimensions in all returned patterns (Pattern.dimCount() is the same as in this one.

      The result of this method and the elements of the result are immutable (Collections.unmodifiableList).

      Specified by:
      allUnionDecompositions in interface Pattern
      Parameters:
      minimalPointCount - this method usually does not decompose patterns that contain less than minimalPointCount points.
      Returns:
      several good variants of decomposition of this pattern to the union of patterns; the result always contains ≥1 elements, and all its elements also contain ≥1 elements.

    • shift

      public WeightedPattern 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.

    • shift

      public abstract WeightedPattern shift(IPoint shift)
      Description copied from interface: WeightedPattern
      Returns the pattern shifted by the argument, that is consisting of points with the same weights, generated from points of this instance by adding the argument via IPoint.add(IPoint) method.
      Specified by:
      shift in interface WeightedPattern
      Parameters:
      shift - the shift.
      Returns:
      the shifted pattern.

    • multiply

      public WeightedPattern multiply(double multiplier)
      Description copied from interface: WeightedPattern
      Returns the pattern consisting of points, generated from points of this instance by multiplying on the mult argument via IPoint.multiply(double) method.

      If mult is not an integer, the generated real coordinates are rounded to integer values. If several source points are rounded to the same integer point, the weights of the resulting points may differ from the weights of the source ones, but the sum of all weights will be approximately same. If the all source points are transformed to different points, their weights are preserved.

      Please note: if mult is not an integer, the algorithm of rounding is not strictly specified! However, you can be sure that the new pattern will be near from the precise result.

      Specified by:
      multiply in interface Pattern
      Specified by:
      multiply in interface WeightedPattern
      Parameters:
      multiplier - the multiplier.
      Returns:
      the product of this pattern and the given scalar mult.
      See Also:

    • scale

      public abstract WeightedPattern 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 WeightedPattern
      Parameters:
      multipliers - the scales along coordinates.
      Returns:
      the scaled pattern.
      See Also:

    • symmetric

      public WeightedPattern symmetric()
      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 WeightedPattern
      Returns:
      the symmetric pattern.

    • weight

      public abstract double weight(IPoint point)
      Description copied from interface: WeightedPattern
      Returns the weight of the given point of the pattern. The result is undefined if this point is outside the pattern.
      Specified by:
      weight in interface WeightedPattern
      Parameters:
      point - some integer point.
      Returns:
      the weight of this point.

    • weightRange

      public abstract Range weightRange()
      Description copied from interface: WeightedPattern
      Returns the minimal and maximal weights of all points of this pattern.
      Specified by:
      weightRange in interface WeightedPattern
      Returns:
      the minimal and maximal weights of all points of this pattern.

    • isConstant

      public boolean isConstant()
      This implementation returns weightRange().size()==0.0. There are no reasons to override this method usually.
      Specified by:
      isConstant in interface WeightedPattern
      Returns:
      true if the weights of all points are the same.

    • productDecomposition

      public List<WeightedPattern> productDecomposition(int minimalPointCount)
      This implementation returns Collections.singletonList(this). Please override this method if there is better implementation.
      Specified by:
      productDecomposition in interface WeightedPattern
      Parameters:
      minimalPointCount - this method does not try to decompose patterns that contain less than minimalPointCount points.
      Returns:
      the decomposition of this pattern to the "product" (convolution) of smaller patterns.
      Throws:
      IllegalArgumentException - if the argument is negative.