public interface UniformGridPattern extends Pattern
Interface, used by Pattern
implementations to indicate that
they are uniformgrid patterns, i.e.
subsets of the set of all mesh nodes of some uniform grids.
See also the section "Uniformgrid patterns" in the comments to Pattern
interface.
More precisely, a pattern, implementing this interface, is some set of N points (N>0)
dimCount()
),
produced by the following formulas:
x_{0}^{(k)} = o_{0} + i_{0}^{(k)}d_{0}
x_{1}^{(k)} = o_{1} + i_{1}^{(k)}d_{1}
. . .
x_{n−1}^{(k)} = o_{n−1} + i_{n−1}^{(k)}d_{n−1}
where o_{j} and d_{j}
are some constants (d_{j}>0)
and i_{j}^{(k)} are any integer numbers.
The point
o=(o_{0},o_{1},...,o_{n−1}),
named origin of the grid, and the vector
d=(d_{0},d_{1},...,d_{n−1}),
named steps of the grid, are specified while creating the pattern.
Moreover, these parameters about (o and d)
are stored inside the object and can be quickly read at any time
by originOfGrid()
and stepsOfGrid()
methods
— this condition is a requirement for all implementations of this interface.
The numbers i_{j}^{(k)} are called grid indexes
of the points of the pattern (or, briefly, grid indexes of the pattern).
The integer points
Pattern
interface),
which is called grid index pattern and can be got at any time by
gridIndexPattern()
method. If the number of points is not extremely large, the grid indexes
can be also retrieved directly as Java set of i^{(k)} points
by gridIndexes()
method.
Warning: not only patterns, implementing this interface, are actually such sets of points.
Moreover, many patterns, created by this package, are really uniform grid
(all their points really belong to set of mesh points of some uniform grid),
but they do not implement this interface and are not considered to be "uniformgrid".
The typical examples are Minkowski sums, created by
Patterns.newMinkowskiSum(Collection)
method,
and unions, created by Patterns.newUnion(Collection)
method.
It is obvious that a Minkowski sum or a union of several uniformgrid patterns, having
zero origin o=(0,0,...,0) and the same steps d, are also uniformgrid patterns
with the same origin and steps. However, it is very probably that the objects, returned by
Patterns.newMinkowskiSum(Collection)
and Patterns.newUnion(Collection)
methods,
will not implement UniformGridPattern
interface even in this "good" case.
There are the following guarantees for grid indexes i_{j}^{(k)} of any uniformgrid pattern:
Pattern.MAX_COORDINATE
≤i_{j}≤Pattern.MAX_COORDINATE
for all j;Pattern.MAX_COORDINATE
for all j.Each implementation of this interface must fulfil both restriction.
Any attempt to create a uniformgrid pattern, the grid indexes of which do not satisfy these restrictions,
leads to TooLargePatternCoordinatesException
.
These restrictions are guaranteed together with the coordinate restrictions,
described in the section "Coordinate restrictions" in the comments to Pattern
interface.
These restrictions provide a guarantee that the method gridIndexPattern()
always
works successfully and creates a correct integer pattern.
AlgART Laboratory 2007–2014
MAX_COORDINATE
Modifier and Type  Method and Description 

UniformGridPattern 
carcass()
Returns the carcass of this pattern.

IRectangularArea 
gridIndexArea()
Returns the minimal and maximal grid index i_{j}
among all points of this pattern
for all coordinate axes j
If a is the result of this method,
then a.
coordCount() ==dimCount()
and a.range (k)
is equal to gridIndexRange (k) for all k. 
java.util.Set<IPoint> 
gridIndexes()
Returns a set of all grid indexes i_{j} of this pattern.

IPoint 
gridIndexMax()
Returns the point, each coordinate #j of which
is equal to the maximal corresponding grid index i_{j}
among all points of this pattern.

IPoint 
gridIndexMin()
Returns the point, each coordinate #j of which
is equal to the minimal corresponding grid index i_{j}
among all points of this pattern.

UniformGridPattern 
gridIndexPattern()
Returns an
ordinary integer pattern with the same set of grid indexes
i_{j}^{(k)} as this pattern. 
IRange 
gridIndexRange(int coordIndex)
Returns the minimal and maximal grid index i_{j}
among all points of this pattern
for the specified coordinate index j==coordIndex.

boolean 
isActuallyRectangular()
Returns true if this pattern is ndimensional rectangular parallelepiped.

boolean 
isOrdinary()
Returns true if and only if this uniformgrid 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.

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
stepOfGrid(coordIndex) 
UniformGridPattern 
maxBound(int coordIndex)
Returns the maximal boundary of this pattern along the given axis:
a pattern consisting of all points of this pattern, for which there are
no other points with greater coordinate #coordIndex
and same other coordinates.

UniformGridPattern 
minBound(int coordIndex)
Returns the minimal boundary of this pattern along the given axis:
a pattern consisting of all points of this pattern, for which there are
no other points with less coordinate #coordIndex
and same other coordinates.

UniformGridPattern 
multiply(double multiplier)
Returns this pattern, scaled by the specified multiplier along all coordinates.

Point 
originOfGrid()
Returns the grid origin o of this pattern.

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

UniformGridPattern 
scale(double... multipliers)
Returns this pattern, scaled by the specified multipliers along all coordinates.

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

UniformGridPattern 
shiftGridIndexes(IPoint shift)
Returns another uniformgrid pattern, identical to this one with the only difference, that
the grid index
add (shift). 
double 
stepOfGrid(int coordIndex)
Returns the grid step d_{j} along the coordinate #j of this pattern
along the coordinate #j=coordIndex.

double[] 
stepsOfGrid()
Returns the array of grid steps d of this pattern.

boolean 
stepsOfGridEqual(UniformGridPattern pattern)
Indicates whether the other uniformgrid pattern has the same grid steps.

Pattern 
surface()
Returns the settheoretical union of all patterns, returned by
lowerSurface(int)
upperSurface(int) methods for all coordinates. 
UniformGridPattern 
symmetric()
Returns the symmetric pattern: equivalent to
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
stepOfGrid(coordIndex) 
allUnionDecompositions, coordArea, coordMax, coordMin, coordRange, dimCount, hasMinkowskiDecomposition, isSurelyInteger, isSurelyOriginPoint, isSurelySinglePoint, largePointCount, maxCarcassMultiplier, minkowskiAdd, minkowskiDecomposition, minkowskiSubtract, pointCount, points, round, roundedCoordArea, roundedCoordRange, roundedPoints, unionDecomposition
Point originOfGrid()
comments to this interface
for more details.
There is a guarantee, that this method always works very quickly
(O(dimCount()
) operations) and without exceptions.
double[] stepsOfGrid()
dimCount()
,
and the element #j contains the grid step d_{j} along the coordinate #j.
See the comments to this interface
for more details.
The returned array is a clone of the internal array of the steps, stored in this object. The returned array is never empty (its length cannot be zero). The elements of the returned array are always positive (<0.0).
There is a guarantee, that this method always works very quickly
(O(dimCount()
) operations) and without exceptions.
double stepOfGrid(int coordIndex)
stepsOfGrid()
[coordIndex], but works faster.
There is a guarantee, that this method always works very quickly
(maximally O(dimCount()
) operations) and without exceptions.
java.lang.IndexOutOfBoundsException
 if coordIndex<0 or
coordIndex>=dimCount()
.boolean stepsOfGridEqual(UniformGridPattern pattern)
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 uniformgrid patterns have identical grid steps, then a Minkowski sum of them
can be also represented by uniformgrid pattern (with same grid steps).
In other case, it is usually impossible — the Minkowski sum, returned by
Pattern.minkowskiAdd(Pattern)
, will not implement UniformGridPattern
.
pattern
 another uniformgrid pattern,
the grid steps of which should be compared with grid steps of this one.java.util.Set<IPoint> gridIndexes()
x_{0}^{(k)} = o_{0} + i_{0}^{(k)}d_{0}
x_{1}^{(k)} = o_{1} + i_{1}^{(k)}d_{1}
. . .
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 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: if you do not really need to get a Java collection of all grid indexes,
you can use 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.
TooManyPointsInPatternError
 if 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).gridIndexPattern()
IRange gridIndexRange(int coordIndex)
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.
coordIndex
 the index j of the coordinate (0 for x, 1 for y, 2 for z, etc.).java.lang.IndexOutOfBoundsException
 if coordIndex<0 or
coordIndex>=dimCount()
.gridIndexMin()
,
gridIndexMax()
,
gridIndexArea()
IRectangularArea gridIndexArea()
coordCount()
==dimCount()
and a.range
(k)
is equal to gridIndexRange
(k) for all k.
All, said in the comments to gridIndexRange(int)
method
about the speed and impossibility of TooManyPointsInPatternError
/ OutOfMemoryError,
is also true for this method.
IPoint gridIndexMin()
gridIndexArea()
.min()
.
All, said in the comments to gridIndexRange(int)
method
about the speed and impossibility of TooManyPointsInPatternError
/ OutOfMemoryError,
is also true for this method.
IPoint gridIndexMax()
gridIndexArea()
.max()
.
All, said in the comments to gridIndexRange(int)
method
about the speed and impossibility of TooManyPointsInPatternError
/ OutOfMemoryError,
is also true for this method.
boolean isOrdinary()
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 "Uniformgrid patterns".
There is a guarantee, that this method always works very quickly
(maximally O(dimCount()
) operations) and without exceptions.
boolean isActuallyRectangular()
origin of the grid
,
d_{j} are steps of the grid
and i_{j} are all integers in the ranges
gridIndexRange(j)
.min()
<=i_{j}<=gridIndexRange(j)
.max()
dimCount()
−1Note that this condition is the same as in the definition of rectangular patterns, represented by
RectangularPattern
interface. Really, if the object implements RectangularPattern
,
this method always returns true. However, this method tries to investigate
the actual point set for other types of patterns.
There are no strict guarantees that this method always returns true if the pattern is ndimensional rectangular parallelepiped. (In some complex situations, such analysis can be too difficult.) But there is this guarantee for all uniformgrid patterns, created by this package. And, of course, there is the reverse guarantee: if this method returns true, the pattern is really a rectangular parallelepiped.
You may be also sure that this method always works quickly enough and without exceptions.
In the worst case, it can require O(N) operations,
N=pointCount()
,
but usually it works much more quickly.
(So, if you implement this method yourself and there is a risk, that calculations
can lead to TooManyPointsInPatternError
, OutOfMemory or another exception due to
extremely large number of points, you must return false instead of
throwing an exception. Please compare this with Pattern.pointCount()
and Pattern.points()
methods,
which do not provide such guarantees and may lead to an exception.)
UniformGridPattern gridIndexPattern()
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_{0}^{(k)} = o_{0} + i_{0}^{(k)}d_{0}
x_{1}^{(k)} = o_{1} + i_{1}^{(k)}d_{1}
. . .
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_{0}^{(k)} = (double)i_{0}^{(k)}
y_{1}^{(k)} = (double)i_{1}^{(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 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()
).
gridIndexes()
UniformGridPattern shiftGridIndexes(IPoint shift)
add
(shift).
In other words, if this pattern is a set of points
x_{0}^{(k)} = o_{0} + i_{0}^{(k)}d_{0}
x_{1}^{(k)} = o_{1} + i_{1}^{(k)}d_{1}
. . .
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_{0}^{(k)} = o_{0} + (i_{0}^{(k)}+shift.coord
(0))*d_{0}
y_{1}^{(k)} = o_{1} + (i_{1}^{(k)}+shift.coord
(1))*d_{1}
. . .
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
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 shift(Point)
method
with a corresponding floatingpoint 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 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 gridIndexPattern()
or gridIndexes()
method.
shift
 the shift of the grid indexes.java.lang.NullPointerException
 if the argument is null.java.lang.IllegalArgumentException
 if point.coordCount()
!=Pattern.dimCount()
.TooLargePatternCoordinatesException
 if the set of shifted points does not fulfil the restrictions,
described in the comments to Pattern
interface,
section "Coordinate restrictions", and in the comments
to UniformGridPattern
interface,
section "Coordinate restrictions".UniformGridPattern lowerSurface(int coordIndex)
stepOfGrid(coordIndex)
dimCount()
) is the same as in this one.
In other words, the point
Please compare with minBound(int)
method. This method can return a pattern
containing more points than 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.
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()
.TooManyPointsInPatternError
 (impossible for implementations, provided by this package)
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).UniformGridPattern upperSurface(int coordIndex)
stepOfGrid(coordIndex)
dimCount()
) is the same as in this one.
In other words, the point
Please compare with maxBound(int)
method. This method can return a pattern
containing more points than 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.
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()
.TooManyPointsInPatternError
 (impossible for implementations, provided by this package)
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 surface()
lowerSurface(int)
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.
TooManyPointsInPatternError
 (impossible for implementations, provided by this package)
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).UniformGridPattern 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.
UniformGridPattern symmetric()
Pattern
multiply(1.0)
.
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.
UniformGridPattern multiply(double multiplier)
Pattern
More precisely, the resulting pattern consists of the points,
obtained from all points of this pattern by the call
point.multiply
(multipliers).
This method is equivalent to Pattern.scale(double... multipliers)
, where all
Pattern.dimCount()
arguments of that method are equal to multiplier.
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 a very large multiplier).
However, such failure is obviously impossible, if the multiplier is
in range 1.0<=multiplier<=1.0.
multiply
in interface Pattern
multiplier
 the scale along all coordinates.Pattern.scale(double...)
UniformGridPattern 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)
UniformGridPattern 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).UniformGridPattern minBound(int coordIndex)
Pattern
Pattern.dimCount()
) is the same as in this one.
In other words, this method removes some points from this pattern according the following rule:
if this pattern contains several points p_{0}, p_{1}, ...,
p_{m−1} with identical projection to the given axis
(p_{i}.projectionAlongAxis
(coordIndex).equals(p_{j}.projectionAlongAxis
(coordIndex)) for all i, j),
then the resulting pattern contains only one from these points, for which
the given coordinate coord
(coordIndex) has the minimal value.
This method is especially useful for uniformgrid
patterns.
For example, in rectangular patterns
this method returns
one of the facets of the hyperparallelepiped.
In most cases (including all rectangular patterns
)
this method returns the same result as lowerSurface(int)
;
but if the figure, described by this pattern, contains some "holes", the result of this method
contains fewer points than lowerSurface(int)
.
The returned pattern always implements DirectPointSetPattern
if this pattern implements DirectPointSetPattern
The returned pattern always implements RectangularPattern
if this pattern implements RectangularPattern
.
The returned pattern always implements UniformGridPattern
if this pattern implements UniformGridPattern
.
Warning! If this object is not DirectPointSetPattern
and is not RectangularPattern
, this method can work slowly for some large patterns:
the required time can be O(N), where N is the number of points.
In these cases, this method can also throw TooManyPointsInPatternError
or OutOfMemoryError. The situation is like in Pattern.points()
and Pattern.roundedPoints()
method.
There is a guarantee, that if this object implements DirectPointSetPattern
interface,
then this method requires not greater than O(N) memory
(N=pointCount()
)
and never throws TooManyPointsInPatternError
.
There is a guarantee, that if this object implements RectangularPattern
interface,
then this method works quickly (O(1) operations) and without exceptions.
minBound
in interface Pattern
coordIndex
 the index of the coordinate (0 for xaxis , 1 for yaxis,
2 for zaxis, etc.).Pattern.maxBound(int)
UniformGridPattern maxBound(int coordIndex)
Pattern
Pattern.dimCount()
) is the same as in this one.
In other words, this method removes some points from this pattern according the following rule:
if this pattern contains several points p_{0}, p_{1}, ...,
p_{m−1} with identical projection to the given axis
(p_{i}.projectionAlongAxis
(coordIndex).equals(p_{j}.projectionAlongAxis
(coordIndex)) for all i, j),
then the resulting pattern contains only one from these points, for which
the given coordinate coord
(coordIndex) has the maximal value.
This method is especially useful for uniformgrid
patterns.
For example, in rectangular patterns
this method returns
one of the facets of the hyperparallelepiped.
In most cases (including all rectangular patterns
)
this method returns the same result as upperSurface(int)
;
but if the figure, described by this pattern, contains some "holes", the result of this method
contains fewer points than upperSurface(int)
.
The returned pattern always implements DirectPointSetPattern
if this pattern implements DirectPointSetPattern
The returned pattern always implements RectangularPattern
if this pattern implements RectangularPattern
.
The returned pattern always implements UniformGridPattern
if this pattern implements UniformGridPattern
.
Warning! If this object is not DirectPointSetPattern
and is not RectangularPattern
, this method can work slowly for some large patterns:
the required time can be O(N), where N is the number of points.
In these cases, this method can also throw TooManyPointsInPatternError
or OutOfMemoryError. The situation is like in Pattern.points()
and Pattern.roundedPoints()
method.
There is a guarantee, that if this object implements DirectPointSetPattern
interface,
then this method requires not greater than O(N) memory
(N=pointCount()
)
and never throws TooManyPointsInPatternError
.
There is a guarantee, that if this object implements RectangularPattern
interface,
then this method works quickly (O(1) operations) and without exceptions.
maxBound
in interface Pattern
coordIndex
 the index of the coordinate (0 for xaxis , 1 for yaxis,
2 for zaxis, etc.).Pattern.minBound(int)
UniformGridPattern carcass()
Pattern
Here A⊕B means the Minkowski sum
of patterns A and B,
k⊗P means P⊕P⊕...⊕P (k summands),
and kP means the pointwise geometrical multiplication of the pattern P by the multiplier k,
i.e. P.multiply
(k).
This method tries to find the minimal carcass, consisting of as little as possible number of points,
and the maximal value n, for which the formulas above are correct for the found carcass.
(The value 2^{n} is called the maximal carcass multiplier
and is returned by Pattern.maxCarcassMultiplier()
method.)
For example, for rectangular patterns
this method returns
the set of vertices of the hyperparallelepiped (in onedimensional case, the pair of segment ends),
and the corresponding n=+∞.
But this method does not guarantee that the returned result is always the minimal possible carcass
and that the found n is really maximal for this carcass.
This method allows to optimize calculation of the point set of a Minkowski multiple k⊗P.
It is really used in the pattern implementations, returned
by Patterns.newMinkowskiMultiplePattern(Pattern, int)
method:
the result of that method is not always an actual Minkowski sum of N equal patterns,
but can be (in the best case) an equal Minkowski sum of ~log_{2}N patterns
In the worst case (no optimization is possible), this method just returns this object (C=P),
and Pattern.maxCarcassMultiplier()
returns 2 (i.e. n=1).
The returned pattern has the same number of dimensions (Pattern.dimCount()
) as this one.
The returned pattern always implements UniformGridPattern
if this pattern implements UniformGridPattern
.
This method can require some time and memory for execution,
but never throws TooManyPointsInPatternError
.