Package net.algart.math.patterns

Class SimplePattern

java.lang.Object
net.algart.math.patterns.AbstractPattern
net.algart.math.patterns.SimplePattern
All Implemented Interfaces:
DirectPointSetPattern, Pattern, QuickPointCountPattern
public class SimplePattern extends AbstractPattern implements DirectPointSetPattern

The simplest implementation of the Pattern interface, based on a set (java.util.Set or some equivalent form), containing all pattern points.

If a pattern is an instance of this class, then there are all common guarantees for DirectPointSetPattern (see the documentation for that interface) and, in addition, you can be sure that points() method works very quickly and does not spend memory: it just returns Collections.unmodifiableSet for the set of points, stored in an internal field.

This class does not support any decompositions: AbstractPattern.hasMinkowskiDecomposition() method returns false, AbstractPattern.minkowskiDecomposition(int), AbstractPattern.unionDecomposition(int) and AbstractPattern.allUnionDecompositions(int) methods return trivial decompositions consisting of the only this pattern.

The methods of pattern transformation — shift(Point), symmetric(), multiply(double), scale(double...), projectionAlongAxis(int), minBound(int), maxBound(int) — always return instances of this class.

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

Author:
Daniel Alievsky

  • Constructor Details

    • SimplePattern

      public SimplePattern(Collection<Point> points)
      Creates a pattern containing the given collection of points.

      This passed collection is cloned by this constructor and converted into java.util.Set. No references to the passed argument are maintained by the created instance.

      Parameters:
      points - collection of all points of the pattern.
      Throws:
      NullPointerException - if the argument is null or if some element in the passed collection is null
      IllegalArgumentException - if points argument is an empty collection, or if some points have different number of coordinates.
      See Also:

  • Method Details

    • pointCount

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

    • 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:

    • isSurelySinglePoint

      public final 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
      Specified by:
      isSurelySinglePoint in class AbstractPattern
      Returns:
      true if it is one-point pattern.
      See Also:

    • shift

      public SimplePattern shift(Point shift)
      This method is implemented here by shifting all points in the point set, stored in this object and returned by points() method, by the call p.add(shift).
      Specified by:
      shift in interface Pattern
      Specified by:
      shift in class AbstractPattern
      Parameters:
      shift - the shift.
      Returns:
      the shifted pattern.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if point.coordCount()!=AbstractPattern.dimCount().
      TooLargePatternCoordinatesException - if the set of shifted points does not fulfil the restrictions, described in the comments to this interface, section "Coordinate restrictions".

    • symmetric

      public SimplePattern 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
      Overrides:
      symmetric in class AbstractPattern
      Returns:
      the symmetric pattern.

    • multiply

      public SimplePattern 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
      Overrides:
      multiply in class AbstractPattern
      Parameters:
      multiplier - the scale along all coordinates.
      Returns:
      the scaled pattern.
      See Also:

    • scale

      public SimplePattern scale(double... multipliers)
      This method is implemented here by scaling all points in the point set, stored in this object and returned by points() method, by the call p.scale(multipliers).
      Specified by:
      scale in interface Pattern
      Specified by:
      scale in class AbstractPattern
      Parameters:
      multipliers - the multipliers for all coordinates.
      Returns:
      the scaled pattern.
      Throws:
      NullPointerException - if the argument is null.
      IllegalArgumentException - if multipliers.length!=dimCount().
      TooLargePatternCoordinatesException - if the set of scaled points does not fulfil the restrictions, described in the comments to this interface, section "Coordinate restrictions".
      See Also:

    • projectionAlongAxis

      public SimplePattern 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 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 SimplePattern minBound(int coordIndex)
      This implementation is similar to the implementation from AbstractPattern class, but (unlike that) this implementation always returns an instance of this class.
      Specified by:
      minBound in interface Pattern
      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.
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=AbstractPattern.dimCount().
      See Also:

    • maxBound

      public SimplePattern maxBound(int coordIndex)
      This implementation is similar to the implementation from AbstractPattern class, but (unlike that) this implementation always returns an instance of this class.
      Specified by:
      maxBound in interface Pattern
      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.
      Throws:
      IndexOutOfBoundsException - if coordIndex<0 or coordIndex>=AbstractPattern.dimCount().
      See Also:

    • toString

      public String toString()
      Returns a brief string description of this object.

      The result of this method may depend on implementation and usually contains the minimum and maximum numbers in this range.

      Overrides:
      toString in class Object
      Returns:
      a brief string description of this object.

    • hashCode

      public final int hashCode()
      Returns the hash code of this pattern. The result depends on all points.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code of this pattern.

    • equals

      public final boolean equals(Object obj)
      Indicates whether some other pattern is equal to this instance, that is the set of its points is the same in terms of java.util.Set.equals method. See more precise specification in comments about equals() in comments to Pattern interface.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to be compared for equality with this instance.
      Returns:
      true if the specified object is a pattern equal to this one.