public abstract class AbstractPattern extends java.lang.Object implements Pattern
A skeletal implementation of the Pattern
interface to minimize
the effort required to implement this interface.
All nonabstract methods are completely implemented here and may be not overridden in subclasses.
AlgART Laboratory 2007–2014
Modifier and Type  Field and Description 

protected int 
dimCount
The number of space dimensions of this pattern.

MAX_COORDINATE
Modifier  Constructor and Description 

protected 
AbstractPattern(int dimCount)
Creates a pattern with the given number of space dimensions.

Modifier and Type  Method and Description 

java.util.List<java.util.List<Pattern>> 
allUnionDecompositions(int minimalPointCount)
This implementation just returns the list containing 1 list, containing
this instance as the only element:
Collections.singletonList(Collections.<Pattern>singletonList(thisInstance)).

Pattern 
carcass()
This implementation just returns this object.

protected void 
checkCoordIndex(int coordIndex)
Throws IndexOutOfBoundsException
if coordIndex<0 or coordIndex>=
dimCount() . 
RectangularArea 
coordArea()
This implementation is based on the loop of calls of
coordRange(int) method
for all coordinate indexes from 0 to dimCount() 1. 
Point 
coordMax()
This implementation is based on the loop of calls of
coordRange(int) method
for all coordinate indexes from 0 to dimCount() 1. 
Point 
coordMin()
This implementation is based on the loop of calls of
coordRange(int) method
for all coordinate indexes from 0 to dimCount() 1. 
abstract 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()
This implementation returns
dimCount field. 
boolean 
hasMinkowskiDecomposition()
This implementation just returns false.

static boolean 
isAllowedCoordRange(Range range)
Returns true if and only if both boundaries of the specified range,
a=range.
min() and b=range.max() ,
lie in range
Pattern.MAX_COORDINATE ≤a≤b≤Pattern.MAX_COORDINATE Patterns.isAllowedDifference (a,b) returns true. 
static boolean 
isAllowedPoint(Point point)
Returns true if and only if all coordinates of the specified point lie
in range −
Pattern.MAX_COORDINATE ≤x_{j}≤Pattern.MAX_COORDINATE . 
boolean 
isPointCountVeryLarge()
This implementation returns false.

boolean 
isSurelyInteger()
This implementation calls
points() method and checks, whether all returned points are integer,
i.e. Point.isInteger() method returns true for all elements the returned set. 
boolean 
isSurelyOriginPoint()
This implementation checks
isSurelySinglePoint() , and if it is true,
checks, whether the only element of points() set is the origin. 
abstract boolean 
isSurelySinglePoint()
Returns true if this pattern consists of the single point, i.e.
if
pointCount() ==1. 
double 
largePointCount()
This implementation returns (double)
pointCount() . 
Pattern 
maxBound(int coordIndex)
This implementation calls
points() method and builds the result on the base of analysis
of the returned point set. 
int 
maxCarcassMultiplier()
This implementation just returns 2.

Pattern 
minBound(int coordIndex)
This implementation calls
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 for all points returned by
points() method in both patterns
and always returns a direct pointset pattern ,
consisting of sums of all point pairs. 
java.util.List<Pattern> 
minkowskiDecomposition(int minimalPointCount)
This implementation just returns Collections.<Pattern>singletonList(thisInstance).

Pattern 
minkowskiSubtract(Pattern subtracted)
This implementation is based on the loop for all points returned by
points() method in both patterns
and always returns a direct pointset pattern . 
Pattern 
multiply(double multiplier)

abstract long 
pointCount()
Returns the number of points in this pattern.

abstract java.util.Set<Point> 
points()
Returns a set of all points of this pattern.

abstract Pattern 
projectionAlongAxis(int coordIndex)
Returns the projection of this pattern along the given axis.

UniformGridPattern 
round()
This implementation calls
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. 
IRectangularArea 
roundedCoordArea()
This implementation is based on the loop of calls of
roundedCoordRange(int) method
for all coordinate indexes from 0 to dimCount() 1. 
IRange 
roundedCoordRange(int coordIndex)
This implementation returns
coordRange (coordIndex).toRoundedRange() . 
java.util.Set<IPoint> 
roundedPoints()
This implementation calls
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 Pattern 
scale(double... multipliers)
Returns this pattern, scaled by the specified multipliers along all coordinates.

abstract Pattern 
shift(Point shift)
Returns this pattern, shifted by the argument.

Pattern 
symmetric()
This implementation calls
multiply(1.0) . 
java.util.List<Pattern> 
unionDecomposition(int minimalPointCount)
This implementation returns
allUnionDecompositions(minimalPointCount) .get(0). 
protected AbstractPattern(int dimCount)
dimCount
 the number of space dimensions.java.lang.IllegalArgumentException
 if dimCount<=0.public final int dimCount()
dimCount
field.public abstract long pointCount()
Pattern
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.
pointCount
in interface Pattern
points
in this pattern.Pattern.largePointCount()
,
Pattern.isSurelySinglePoint()
,
QuickPointCountPattern.isPointCountVeryLarge()
public double largePointCount()
pointCount()
.
Please override this method if the pattern can contain more than Long.MAX_VALUE points.largePointCount
in interface Pattern
integer points
in this pattern.QuickPointCountPattern.isPointCountVeryLarge()
public boolean isPointCountVeryLarge()
public abstract java.util.Set<Point> points()
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 nonempty,
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
TooManyPointsInPatternError
)
for n=2000 (2000^{3}>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.
public java.util.Set<IPoint> roundedPoints()
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.roundedPoints
in interface Pattern
TooManyPointsInPatternError
 if points()
method throws this exception
(OutOfMemoryError can be also thrown in this case).public abstract Range coordRange(int coordIndex)
Pattern
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.
coordRange
in interface Pattern
coordIndex
 the index of the coordinate (0 for x, 1 for y, 2 for z, etc.).Pattern.roundedCoordRange(int)
,
Pattern.coordMin()
,
Pattern.coordMax()
,
Pattern.coordArea()
public RectangularArea coordArea()
coordRange(int)
method
for all coordinate indexes from 0 to dimCount()
1.coordArea
in interface Pattern
Pattern.roundedCoordArea()
public Point coordMin()
coordRange(int)
method
for all coordinate indexes from 0 to dimCount()
1.public Point coordMax()
coordRange(int)
method
for all coordinate indexes from 0 to dimCount()
1.public IRange roundedCoordRange(int coordIndex)
coordRange
(coordIndex).toRoundedRange()
.roundedCoordRange
in interface Pattern
coordIndex
 the index of the coordinate (0 for x, 1 for y, 2 for z, etc.).java.lang.IndexOutOfBoundsException
 if coordIndex<0 or coordIndex>=dimCount()
.Pattern.roundedCoordArea()
public IRectangularArea roundedCoordArea()
roundedCoordRange(int)
method
for all coordinate indexes from 0 to dimCount()
1.roundedCoordArea
in interface Pattern
public abstract boolean isSurelySinglePoint()
Pattern
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 floatingpoint precision can lead to equality of all points of the result.
Simple example: a Minkowski sum of twopoint onedimensional pattern, consisting of points
0.0 and 0.000001, and onepoint 2^{51}=2251799813685248.0, contains only 1 point 2^{51},
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).
isSurelySinglePoint
in interface Pattern
Pattern.isSurelyOriginPoint()
public boolean isSurelyOriginPoint()
isSurelySinglePoint()
, and if it is true,
checks, whether the only element of points()
set is the origin.
This method caches its results: the following calls will work faster.
isSurelyOriginPoint
in interface Pattern
Pattern.isSurelySinglePoint()
public boolean isSurelyInteger()
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 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 minkowskiDecomposition(int)
,
unionDecomposition(int)
and allUnionDecompositions(int)
methods
have default implementations (not overridden). If some of them are overridden and
return some nontrivial 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
points()
method leads to a risk of TooManyPointsInPatternError
/ OutOfMemoryError.
In particular, this method should be usually overridden in implementations of RectangularPattern
.
isSurelyInteger
in interface Pattern
integer
points.public UniformGridPattern round()
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.round
in interface Pattern
TooManyPointsInPatternError
 if this pattern is not DirectPointSetPattern
and
not RectangularPattern
and if, at the same time, the number
of points is greater than Integer.MAX_VALUE or,
in some rare situations, is near this limit
(OutOfMemoryError can be also thrown instead of this exception).public abstract Pattern projectionAlongAxis(int coordIndex)
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.
projectionAlongAxis
in interface Pattern
coordIndex
 the index of the coordinate (0 for xaxis , 1 for yaxis,
2 for zaxis, etc.).Pattern.dimCount()
is equal to
thisInstance.Pattern.dimCount()
1).public Pattern minBound(int coordIndex)
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.minBound
in interface Pattern
coordIndex
 the index of the coordinate (0 for xaxis , 1 for yaxis,
2 for zaxis, etc.).java.lang.IndexOutOfBoundsException
 if coordIndex<0 or coordIndex>=dimCount()
.TooManyPointsInPatternError
 if this pattern is not DirectPointSetPattern
and
not RectangularPattern
and if, at the same time, the number
of points is greater than Integer.MAX_VALUE or,
in some rare situations, is near this limit
(OutOfMemoryError can be also thrown instead of this exception).Pattern.maxBound(int)
public Pattern maxBound(int coordIndex)
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.maxBound
in interface Pattern
coordIndex
 the index of the coordinate (0 for xaxis , 1 for yaxis,
2 for zaxis, etc.).java.lang.IndexOutOfBoundsException
 if coordIndex<0 or coordIndex>=dimCount()
.TooManyPointsInPatternError
 if this pattern is not DirectPointSetPattern
and
not RectangularPattern
and if, at the same time, the number
of points is greater than Integer.MAX_VALUE or,
in some rare situations, is near this limit
(OutOfMemoryError can be also thrown instead of this exception).Pattern.minBound(int)
public Pattern carcass()
maxCarcassMultiplier()
),
if your class can provide better results.
Note: AbstractUniformGridPattern
class provides much better implementation.
public int maxCarcassMultiplier()
carcass()
),
if your class can provide better results.
Note: AbstractUniformGridPattern
class provides much better implementation.
maxCarcassMultiplier
in interface Pattern
carcass
.public abstract Pattern shift(Point shift)
Pattern
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
coord
(j)TooLargePatternCoordinatesException
in the following situations:
coordMin()
.symmetric()
,coordMax()
.symmetric()
,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.
public Pattern symmetric()
multiply(1.0)
.
There are no reasons to override this method usually.public Pattern multiply(double multiplier)
dimCount
]scale(a)
.
There are no reasons to override this method usually.multiply
in interface Pattern
multiplier
 the scale along all coordinates.TooLargePatternCoordinatesException
 if the set of scaled points does not fulfil the restrictions,
described in the comments to Pattern
interface,
section "Coordinate restrictions".Pattern.scale(double...)
public abstract Pattern scale(double... multipliers)
Pattern
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.
scale
in interface Pattern
multipliers
 the scales along coordinates.Pattern.multiply(double)
public Pattern minkowskiAdd(Pattern added)
points()
method in both patterns
and always returns a direct pointset 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.minkowskiAdd
in interface Pattern
added
 another pattern.java.lang.NullPointerException
 if the argument is null.java.lang.IllegalArgumentException
 if the numbers of space dimensions of both patterns are different.TooManyPointsInPatternError
 for some forms of large patterns, if the number of points in this,
added or result pattern is greater than
Integer.MAX_VALUE or, maybe, is near this limitTooLargePatternCoordinatesException
 if the resulting set of points does not fulfil the restrictions,
described in the comments to Pattern
interface,
section "Coordinate restrictions".Patterns.newMinkowskiSum(java.util.Collection)
,
Pattern.minkowskiSubtract(Pattern)
public Pattern minkowskiSubtract(Pattern subtracted)
points()
method in both patterns
and always returns a direct pointset pattern
.
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.minkowskiSubtract
in interface Pattern
subtracted
 another pattern.java.lang.NullPointerException
 if the argument is null.java.lang.IllegalArgumentException
 if the numbers of space dimensions of both patterns are different.TooManyPointsInPatternError
 for some forms of large patterns, if the number of points in this,
subtracted or result pattern is greater than
Integer.MAX_VALUE or, maybe, is near this limitTooLargePatternCoordinatesException
 if the resulting set of points does not fulfil the restrictions,
described in the comments to Pattern
interface,
section "Coordinate restrictions".Pattern.minkowskiAdd(Pattern)
public java.util.List<Pattern> minkowskiDecomposition(int minimalPointCount)
Note: AbstractUniformGridPattern
class provides much better implementation for
patterns, recognized as rectangular by UniformGridPattern.isActuallyRectangular()
method.
minkowskiDecomposition
in interface Pattern
minimalPointCount
 this method usually does not decompose patterns that contain
less than minimalPointCount points.java.lang.IllegalArgumentException
 if the argument is negative.public boolean hasMinkowskiDecomposition()
hasMinkowskiDecomposition
in interface Pattern
public java.util.List<Pattern> unionDecomposition(int minimalPointCount)
allUnionDecompositions(minimalPointCount)
.get(0).unionDecomposition
in interface Pattern
minimalPointCount
 this method usually does not decompose patterns that contain
less than minimalPointCount points.java.lang.IllegalArgumentException
 if the argument is negative.public java.util.List<java.util.List<Pattern>> allUnionDecompositions(int minimalPointCount)
Note: AbstractUniformGridPattern
class provides much better implementation.
allUnionDecompositions
in interface Pattern
minimalPointCount
 this method usually does not decompose patterns that contain
less than minimalPointCount points.java.lang.IllegalArgumentException
 if the argument is negative.public static boolean isAllowedPoint(Point point)
Pattern.MAX_COORDINATE
≤x_{j}≤Pattern.MAX_COORDINATE
.
Actually this method checks the 1st restriction for coordinates of any pattern:
see comments to Pattern
interface, section "Coordinate restrictions".
point
 some point.java.lang.NullPointerException
 if the argument is null.public static boolean isAllowedCoordRange(Range range)
min()
and b=range.max()
,
lie in range
Pattern.MAX_COORDINATE
≤a≤b≤Pattern.MAX_COORDINATE
Patterns.isAllowedDifference
(a,b) returns true.
This method helps to check the 2nd restriction for coordinates of any pattern:
see comments to Pattern
interface, section "Coordinate restrictions".
range
 some range.java.lang.NullPointerException
 if the argument is null.protected final void checkCoordIndex(int coordIndex)
dimCount()
.
Does nothing in other case.coordIndex
 checked index of the coordinate.java.lang.IndexOutOfBoundsException
 if coordIndex<0 or coordIndex>=dimCount()
.