Package net.algart.math.patterns

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

Field Summary

Fields inherited from class net.algart.math.patterns.AbstractPattern

dimCount

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

MAX_COORDINATE

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
List<List<Pattern>>	allUnionDecompositions(int minimalPointCount)	This implementation uses a common algorithm that usually provide good results.
UniformGridPattern	carcass()	//TODO!! - that it checks isActuallyRectangular() This method is fully implemented in this class and usually should not be overridden.
Range	coordRange(int coordIndex)	Returns the minimal and maximal coordinate with the given index (Point.coord(coordIndex)) among all points of this pattern.
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.
abstract Set<IPoint>	gridIndexes()	Returns a set of all grid indexes ij of this pattern.
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.
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.
abstract UniformGridPattern	gridIndexPattern()	Returns an ordinary integer pattern with the same set of grid indexes ij(k) as this pattern.
abstract IRange	gridIndexRange(int coordIndex)	Returns the minimal and maximal grid index ij among all points of this pattern for the specified coordinate index j==coordIndex.
protected String	gridToString()
boolean	hasMinkowskiDecomposition()	This implementation returns minkowskiDecomposition(0).size()>1.
boolean	isActuallyRectangular()	This implementation returns true if and only if pointCount()=r0r1...<Long.MAX_VALUE, where ri=gridIndexRange(i).size().
static boolean	isAllowedGridIndex(IPoint gridIndex)
static boolean	isAllowedGridIndexRange(IRange gridIndexRange)
final boolean	isOrdinary()	Returns true if and only if this uniform-grid pattern is an ordinary integer pattern, i.e. if the grid origin o is the origin of coordinates (0,0,...,0) and all grid steps dj are 1.0.
boolean	isSurelyInteger()	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.
UniformGridPattern	lowerSurface(int coordIndex)	Returns the lower boundary of this pattern along the given axis: a pattern consisting of all such points A of this pattern, that the neighbour point B, generated by the backward shift of point A along the coordinate #j=coordIndex by the corresponding grid step dj=stepOfGrid(coordIndex), does not belong to this pattern.
UniformGridPattern	maxBound(int coordIndex)	This implementation calls AbstractPattern.points() method and builds the result on the base of analysis of the returned point set.
int	maxCarcassMultiplier()	//TODO!! - write that it checks isActuallyRectangular() This method is fully implemented in this class and usually should not be overridden.
UniformGridPattern	minBound(int coordIndex)	This implementation calls AbstractPattern.points() method and builds the result on the base of analysis of the returned point set.
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.
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.
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.
UniformGridPattern	multiply(double multiplier)	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).
Point	originOfGrid()	This implementation returns the grid origin, specified in the constructor.
abstract long	pointCount()	Returns the number of points in this pattern.
Set<Point>	points()	Returns a set of all points of this pattern.
abstract UniformGridPattern	projectionAlongAxis(int coordIndex)	Returns the projection of this pattern along the given axis.
UniformGridPattern	round()	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.
Set<IPoint>	roundedPoints()	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.
abstract UniformGridPattern	scale(double... multipliers)	Returns this pattern, scaled by the specified multipliers along all coordinates.
abstract UniformGridPattern	shift(Point shift)	Returns this pattern, shifted by the argument.
abstract UniformGridPattern	shiftGridIndexes(IPoint shift)	Returns another uniform-grid pattern, identical to this one with the only difference, that the grid index i(k) = (i0(k), i1(k), ..., in−1(k)) for each point #k of the result is shifted by the argument of this method via the call i(k).add(shift).
double	stepOfGrid(int coordIndex)	Returns the grid step dj along the coordinate #j of this pattern along the coordinate #j=coordIndex.
double[]	stepsOfGrid()	This implementation returns a new copy of Java array of grid steps, specified in the constructor.
boolean	stepsOfGridEqual(UniformGridPattern pattern)	Indicates whether the other uniform-grid pattern has the same grid steps.
Pattern	surface()	Returns the set-theoretical union of all patterns, returned by UniformGridPattern.lowerSurface(int) UniformGridPattern.upperSurface(int) methods for all coordinates.
UniformGridPattern	symmetric()	This implementation calls multiply(-1.0).
UniformGridPattern	upperSurface(int coordIndex)	Returns the upper boundary of this pattern along the given axis: a pattern consisting of all such points A of this pattern, that the neighbour point B, generated by the forward shift of point A along the coordinate #j=coordIndex by the corresponding grid step dj=stepOfGrid(coordIndex), does not belong to this pattern.

Methods inherited from class net.algart.math.patterns.AbstractPattern

checkCoordIndex, coordArea, coordMax, coordMin, dimCount, isAllowedCoordRange, isAllowedPoint, isPointCountVeryLarge, isSurelyOriginPoint, isSurelySinglePoint, largePointCount, roundedCoordArea, roundedCoordRange, unionDecomposition

Methods inherited from class java.lang.Object

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

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

coordArea, coordMax, coordMin, dimCount, isSurelyOriginPoint, isSurelySinglePoint, largePointCount, roundedCoordArea, roundedCoordRange, unionDecomposition

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 d_j 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 i_j of this pattern. Namely, the elements of the returned set contain grid indexes i^(k) = (i₀^(k), i₁^(k), ..., i_n−1^(k)) of all points x^(k) = (x₀^(k), x₁^(k), ..., x_n−1^(k)) of this pattern:

x₀^(k) = o₀ + i₀^(k)d₀
x₁^(k) = o₁ + i₁^(k)d₁
. . .
x_n−1^(k) = o_n−1 + i_n−1^(k)d_n−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 (2000³>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:

• UniformGridPattern.gridIndexPattern()

gridIndexRange

public abstract IRange gridIndexRange(int coordIndex)

Description copied from interface: UniformGridPattern

Returns the minimal and maximal grid index i_j 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 i_j.

See Also:

• UniformGridPattern.gridIndexMin()
• UniformGridPattern.gridIndexMax()
• UniformGridPattern.gridIndexArea()

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 d_j 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 d_j=1.0.

isActuallyRectangular

public boolean isActuallyRectangular()

This implementation returns true if and only if pointCount()=r₀r₁...<Long.MAX_VALUE, where r_i=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 i_j^(k) as this pattern. In other words, if this pattern is a set of points

x₀^(k) = o₀ + i₀^(k)d₀
x₁^(k) = o₁ + i₁^(k)d₁
. . .
x_n−1^(k) = o_n−1 + i_n−1^(k)d_n−1

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

y₀^(k) = (double)i₀^(k)
y₁^(k) = (double)i₁^(k)
. . .
y_n−1^(k) = (double)i_n−1^(k)

Note: here is a guarantee, that all grid indexes i_j 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:

• UniformGridPattern.gridIndexes()

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) = (i₀^(k), i₁^(k), ..., i_n−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

x₀^(k) = o₀ + i₀^(k)d₀
x₁^(k) = o₁ + i₁^(k)d₁
. . .
x_n−1^(k) = o_n−1 + i_n−1^(k)d_n−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

y₀^(k) = o₀ + (i₀^(k)+shift.coord(0))*d₀
y₁^(k) = o₁ + (i₁^(k)+shift.coord(1))*d₁
. . .
y_n−1^(k) = o_n−1 + (i_n−1^(k)+shift.coord(n−1))*d_n−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 d_j=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 = (x₀, x₁, ..., x_j, ..., x_n−1) belongs to the returned pattern if and only if it belongs to this pattern and the point B = (x₀, x₁, ..., x_j−d_j, ..., x_n−1) (corresponding to decreasing the grid index i_j 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 d_j=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 = (x₀, x₁, ..., x_j, ..., x_n−1) belongs to the returned pattern if and only if it belongs to this pattern and the point B = (x₀, x₁, ..., x_j+d_j, ..., x_n−1) (corresponding to increasing the grid index i_j 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:

• Pattern.largePointCount()
• Pattern.isSurelySinglePoint()
• QuickPointCountPattern.isPointCountVeryLarge()

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 (2000³>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:

• Pattern.roundedCoordRange(int)
• Pattern.coordMin()
• Pattern.coordMax()
• Pattern.coordArea()

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:

• Pattern.maxBound(int)

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:

• Pattern.minBound(int)

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 X_j=shift.coord(j) of the argument is equal to −x_j for some some point (x₀, x₁, ..., x_n−1) of this pattern. In particular, you can use this method for integer patterns without a risk of TooLargePatternCoordinatesException in the following situations:

• shift is thisIntegerPattern.coordMin().symmetric(),
• shift is thisIntegerPattern.coordMax().symmetric(),
• shift is p.symmetric(), where p is some of the points if this integer pattern.

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:

• Pattern.scale(double...)

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:

• Pattern.multiply(double)

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:

• Patterns.newMinkowskiSum(java.util.Collection)
• Pattern.minkowskiSubtract(Pattern)

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:

• Pattern.minkowskiAdd(Pattern)

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()