Package net.algart.math.patterns

Class Patterns

java.lang.Object
net.algart.math.patterns.Patterns
public class Patterns extends Object

A set of static methods operating with and returning patterns.

This class cannot be instantiated.

Author:
Daniel Alievsky

  • Method Details

    • newPattern

      public static DirectPointSetPattern newPattern(Collection<Point> points)

    • newPattern

      public static DirectPointSetPattern newPattern(Point... points)

    • newUniformGridPattern

      public static DirectPointSetUniformGridPattern newUniformGridPattern(Point originOfGrid, double[] stepsOfGrid, Collection<IPoint> gridIndexes)

    • newIntegerPattern

      public static DirectPointSetUniformGridPattern newIntegerPattern(Collection<IPoint> points)
      Creates new pattern consisting of all specified points.

      The returned pattern is so-called simple, or multipoint pattern: it means that its implementation is based on a usual set of IPoint instances. For such pattern, the number of dimensions is equal to the number of coordinates in all passed points (it must be the same for all source points). The UniformGridPattern.isActuallyRectangular() method is non-overridden AbstractUniformGridPattern.isActuallyRectangular() method. The Pattern.minkowskiAdd(Pattern) method returns a new simple pattern according the definition of Minkowski sum; this method requires O(NM) operations, where N and M is the number of points in both patterns, and may work slowly. The Pattern.minkowskiDecomposition(int) method returns the list containing this pattern instance as the only element. The equals method returns true if and only if the passed object is also simple pattern, consisting of the same points and created by this or equivalent method from this package.

      The coordinates of all points must be in range -Long.MAX_VALUE/2..Long.MAX_VALUE/2, excepting the only case when the number of points is 1.

      The returned pattern will be "safe" in the sense that no references to the passed set are maintained by it. In other words, this method always allocates new set (probably HashSet) and copies the passed set into it.

      Parameters:
      points - the source points set.
      Returns:
      the pattern consisting of all source points.
      Throws:
      NullPointerException - if points argument is null or some of passed points is null.
      IllegalArgumentException - if points argument is an empty set, or if some points have different number of coordinates, or if there are 2 or more points and some point coordinates are out of range -Long.MAX_VALUE/2..Long.MAX_VALUE/2.

    • newIntegerPattern

      public static DirectPointSetUniformGridPattern newIntegerPattern(IPoint... points)
      Equivalent to newIntegerPattern(new HashSet(Arrays.asList(points))).
      Parameters:
      points - the source points set.
      Returns:
      the pattern consisting of all source points.
      Throws:
      NullPointerException - if points argument is null or some of passed points is null.
      IllegalArgumentException - if points argument is an empty array, or if some points have different number of coordinates, or if there are 2 or more points and some point coordinates are out of range -Long.MAX_VALUE/2..Long.MAX_VALUE/2.

    • newSphereIntegerPattern

      public static UniformGridPattern newSphereIntegerPattern(Point center, double r)
      A concrete variant of newIntegerPattern(java.util.Collection<net.algart.math.IPoint>) method returning the pattern consisting of all such points inside n-dimensional sphere with the given radius r and center.

      More precisely, let C=(c0,c1,...,cn-1) is the passed center point. The result of this method consists of all points A=(x0,x1,...,xn-1) that |OA|2 = (x0-c0)2 + (x1-c1)2 + ... + (xn-1-cn-1)2 ≤ r2.

      The Pattern.roundedCoordRange(int) method in the returned pattern works very quickly, unlike patterns created by newIntegerPattern(java.util.Collection<net.algart.math.IPoint>) method.

      Please note: integer values of the radius usually produce "non-beautiful" patterns with very uneven edges. For example, in 2-dimensional case (circles) we recommend to pass r~k-0.2, where k is a positive integer.

      Please be careful: too large values of r argument may lead to very long execution and even to OutOfMemoryError, especially for 2- and 3-dimensional patterns. Moreover, there are no ways to interrupt this method or to show its execution progress. We recommend to restrict the passed radius by some suitable value, for example, 1000–2000 or less.

      Parameters:
      center - the center of the sphere (circle in 2-dimensional case).
      r - the radius of the sphere.
      Returns:
      the pattern consisting of all points inside this sphere (circle in 2-dimensional case).
      Throws:
      IllegalArgumentException - if r<0.0,
      TooManyPointsInPatternError - if r is about Integer.MAX_VALUE or greater.

    • newEllipsoidIntegerPattern

      public static UniformGridPattern newEllipsoidIntegerPattern(Point center, double... semiAxes)

    • newSurface

      public static Pattern newSurface(Pattern projection, Func surface)

    • newSpaceSegment

      public static UniformGridPattern newSpaceSegment(UniformGridPattern projection, Func minSurface, Func maxSurface, double lastCoordinateOfOrigin, double lastCoordinateStep)

    • newRectangularUniformGridPattern

      public static RectangularPattern newRectangularUniformGridPattern(Point originOfGrid, double[] stepsOfGrid, IRange... gridIndexRanges)

    • newRectangularIntegerPattern

      public static RectangularPattern newRectangularIntegerPattern(IRange... ranges)
      Creates new rectangular pattern (n-dimensional rectangular parallelepiped), consisting of all such points (x0,x1,...,xn-1) that ranges[i].min()<=xi<=ranges[i].max(), i=0,1,...,n-1, n=ranges.length. The number of space dimensions of the returned pattern will be equal to the length of ranges array.

      In the returned pattern, the UniformGridPattern.isActuallyRectangular() method returns true always. The Pattern.minkowskiAdd(Pattern) method creates a new rectangular pattern (via this method), if its argument is also rectangular, according the definition of Minkowski sum; in other case, it returns new simple pattern and works slowly (O(NM) operations, where N and M is the number of points in both patterns). The Pattern.minkowskiDecomposition(int) method returns the list containing ~log2(N) 2-point simple patterns or, maybe, the list containing one 1-point pattern if this rectangular pattern is degenerate (1-point). The equals method returns true if and only if the passed object is also rectangular pattern, consisting of the same points and created by this or equivalent method from this package.

      The returned pattern will be "safe" in the sense that no references to the passed array are maintained by it. In other words, this method always allocates new array for storing ranges and copies the passed ranges into it.

      Parameters:
      ranges - the source ranges describing n-dimensional rectangular parallelepiped.
      Returns:
      the rectangular pattern.
      Throws:
      NullPointerException - if ranges argument is null or some of passed ranges are null.
      IllegalArgumentException - if ranges argument is empty (contains no elements).

    • newRectangularIntegerPattern

      public static UniformGridPattern newRectangularIntegerPattern(IPoint min, IPoint max)
      Equivalent to newRectangularIntegerPattern(ranges), where ranges[k] is IRange.valueOf(min.coord(k), max.coord(k)). The number of dimensions of the created pattern is equal to the number of coordinates of min and max points.

      The number of coordinates of min and max points must be the same. All coordinates of min point must not be greater than the corresponding coordinates of the max points.

      Parameters:
      min - starting points of the parallelepiped (left top vertex in 2D case), inclusive.
      max - ending points of the parallelepiped (left top vertex in 2D case), inclusive.
      Returns:
      the rectangular pattern, two vertices of which are the passed points.
      Throws:
      NullPointerException - if one of the arguments is null.
      IllegalArgumentException - if the numbers of coordinates of min and max points are different, or if min.coord(k) > max.coord(k) for some k, or if the difference between these coordinates is >=Long.MAX_VALUE.

    • newMinkowskiSum

      public static Pattern newMinkowskiSum(Pattern... patterns)
      Creates new pattern, representing the Minkowski sum of all passed patterns. Please see Wikipedia about the "Minkowski sum" term. See also Pattern.minkowskiAdd(Pattern) method for comparison.

      Note: this method does not actually calculate the point set of the sum; if necessary, you will be able to get all points later by Pattern.roundedPoints() method.

      In the returned pattern, the Pattern.minkowskiDecomposition(int) method returns the summary list of Minkowski decompositions of all patterns passed to this method. The UniformGridPattern.isActuallyRectangular() method is non-overridden AbstractUniformGridPattern.isActuallyRectangular() method. The Pattern.minkowskiAdd(Pattern) method creates a new Minkowski sum by this method, that contains an additional summand equal to the added pattern. The equals method returns true if and only if the passed object is also Minkowski sum, consisting of the same summands and created by this or equivalent method from this package.

      If all passed patterns are rectangular, the behavior of this method is another: it just returns new rectangular pattern equal to the Minkowski sum of all passed patterns.

      The returned pattern will be "safe" in the sense that no references to the passed array are maintained by it. In other words, this method always allocates new array for storing summands and copies the passed summands into it.

      Parameters:
      patterns - the summands of the returned Minkowski sum.
      Returns:
      the Minkowski sum.
      Throws:
      NullPointerException - if patterns argument is null or some of passed patterns are null.
      IllegalArgumentException - if patterns argument is an empty array, or if some patterns have different number of dimensions, or if some of the coordinate ranges in the precise result are out of Long.MIN_VALUE..Long.MAX_VALUE range or have the size (maximum - minimum), greater or equal to Long.MAX_VALUE.

    • newMinkowskiSum

      public static Pattern newMinkowskiSum(Collection<Pattern> patterns)

    • newMinkowskiMultiplePattern

      public static Pattern newMinkowskiMultiplePattern(Pattern pattern, int n)
      Equivalent to newMinkowskiSum(patterns), where pattern is the array with the length n containing n copies of the passed pattern. Some algorithms of this package work better with such form of the Minkowski sums.
      Parameters:
      pattern - the pattern.
      n - the multiplier.
      Returns:
      the Minkowski multiple of the passed pattern.
      Throws:
      NullPointerException - if pattern argument is null.
      IllegalArgumentException - if n <= 0.

    • newUnion

      public static Pattern newUnion(Pattern... patterns)
      Creates new pattern, representing the set-theoretic union of the passed patterns. This method does not calculate the point set of the union; if necessary, you will be able to get all points later by Pattern.roundedPoints() method.

      In the returned pattern, the Pattern.unionDecomposition(int) method returns the summary list of union decompositions of all patterns passed to this method, and the Pattern.allUnionDecompositions(int) method returns the same list as the only element of its result. The Pattern.minkowskiDecomposition(int) method is non-overridden AbstractPattern.minkowskiDecomposition(int) method. The UniformGridPattern.isActuallyRectangular() method is non-overridden AbstractUniformGridPattern.isActuallyRectangular() method. The Pattern.minkowskiAdd(Pattern) method returns a new simple pattern according the definition of Minkowski sum; this method requires O(NM) operations, where N and M is the number of points in both patterns, and may work slowly. The Pattern.minkowskiDecomposition(int) method returns the list containing this pattern instance as the only element. The equals method returns true if and only if the passed object is also union of patterns, consisting of the same summands and created by this or equivalent method from this package.

      The returned pattern will be "safe" in the sense that no references to the passed array are maintained by it. In other words, this method always allocates new array for storing summands and copies the passed summands into it.

      Parameters:
      patterns - the summands of the returned union.
      Returns:
      the set-theoretic union.
      Throws:
      NullPointerException - if patterns argument is null or some of passed patterns are null.
      IllegalArgumentException - if patterns argument is an empty array, or if some patterns have different number of dimensions, or if some of the coordinate ranges in the precise result have the size (maximum - minimum), greater or equal to Long.MAX_VALUE.

    • newUnion

      public static Pattern newUnion(Collection<Pattern> patterns)

    • isAllowedDifference

      public static boolean isAllowedDifference(double x1, double x2)
      Returns true if and only if the absolute value of the precise mathematical difference |x1−x2| is not greater than Pattern.MAX_COORDINATE: |x1−x2|≤Pattern.MAX_COORDINATE.

      Note: this condition is checked absolutely strictly with ideal precision. If this difference is near to Pattern.MAX_COORDINATE value, this method uses BigDecimal class to provide absolutely correct result.

      Special cases: if any of two arguments contains NaN or an infinity, this method returns false.

      Parameters:
      x1 - the first number.
      x2 - the second number.
      Returns:
      if the mathematically precise difference between these numbers is ≤Pattern.MAX_COORDINATE.