Package net.algart.math.patterns

Interface DirectPointSetUniformGridPattern

All Superinterfaces:

DirectPointSetPattern, Pattern, QuickPointCountPattern, UniformGridPattern

public interface DirectPointSetUniformGridPattern
extends DirectPointSetPattern, UniformGridPattern

Interface, used by Pattern implementations to indicate that they are simultaneously DirectPointSetPattern and UniformGridPattern. In other words, a pattern implements this interface if and only if it is simultaneously direct point-set and uniform-grid: see the corresponding sections in the comments to Pattern interface.

If a pattern implements this interface, it never implements RectangularPattern interface.

There is a guarantee, that the following methods create patterns, implementing this interface:

• Patterns.newUniformGridPattern(net.algart.math.Point, double[], java.util.Collection),
• Patterns.newIntegerPattern(net.algart.math.IPoint...),
• Patterns.newIntegerPattern(java.util.Collection),
• Patterns.newSphereIntegerPattern(net.algart.math.Point, double),
• Patterns.newEllipsoidIntegerPattern(net.algart.math.Point, double...),
• Patterns.newSpaceSegment(UniformGridPattern, Func, Func, double, double).

The following methods can return an object, implementing this interface, and also an object, not implementing this interface — it depends on their arguments:

• Patterns.newPattern(net.algart.math.Point...),
• Patterns.newPattern(java.util.Collection),

Author:

Daniel Alievsky

See Also:

• QuickPointCountPattern

Field Summary

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

MAX_COORDINATE

Method Summary

Modifier and Type	Method	Description
DirectPointSetUniformGridPattern	gridIndexPattern()	Returns an ordinary integer pattern with the same set of grid indexes ij(k) as this pattern.
DirectPointSetUniformGridPattern	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.
DirectPointSetUniformGridPattern	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.
DirectPointSetUniformGridPattern	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.
DirectPointSetUniformGridPattern	multiply(double multiplier)	Returns this pattern, scaled by the specified multiplier along all coordinates.
DirectPointSetUniformGridPattern	projectionAlongAxis(int coordIndex)	Returns the projection of this pattern along the given axis.
DirectPointSetUniformGridPattern	scale(double... multipliers)	Returns this pattern, scaled by the specified multipliers along all coordinates.
DirectPointSetUniformGridPattern	shift(Point shift)	Returns this pattern, shifted by the argument.
DirectPointSetUniformGridPattern	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).
DirectPointSetUniformGridPattern	symmetric()	Returns the symmetric pattern: equivalent to multiply(-1.0).
DirectPointSetUniformGridPattern	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 interface net.algart.math.patterns.Pattern

allUnionDecompositions, coordArea, coordMax, coordMin, coordRange, dimCount, hasMinkowskiDecomposition, isSurelyInteger, isSurelyOriginPoint, isSurelySinglePoint, largePointCount, maxCarcassMultiplier, minkowskiAdd, minkowskiDecomposition, minkowskiSubtract, pointCount, points, round, roundedCoordArea, roundedCoordRange, roundedPoints, unionDecomposition

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

isPointCountVeryLarge

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

carcass, gridIndexArea, gridIndexes, gridIndexMax, gridIndexMin, gridIndexRange, isActuallyRectangular, isOrdinary, originOfGrid, stepOfGrid, stepsOfGrid, stepsOfGridEqual, surface

Method Details

shift

DirectPointSetUniformGridPattern 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

Parameters:

shift - the shift.

Returns:

the shifted pattern.

symmetric

DirectPointSetUniformGridPattern symmetric()

Description copied from interface: Pattern

Returns the symmetric pattern: equivalent to 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.

Specified by:

symmetric in interface Pattern

Specified by:

symmetric in interface UniformGridPattern

Returns:

the symmetric pattern.

multiply

DirectPointSetUniformGridPattern multiply(double multiplier)

Description copied from interface: Pattern

Returns this pattern, scaled by the specified multiplier along all coordinates.

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.

Specified by:

multiply in interface Pattern

Specified by:

multiply in interface UniformGridPattern

Parameters:

multiplier - the scale along all coordinates.

Returns:

the scaled pattern.

See Also:

• Pattern.scale(double...)

scale

DirectPointSetUniformGridPattern 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

Parameters:

multipliers - the scales along coordinates.

Returns:

the scaled pattern.

See Also:

• Pattern.multiply(double)

projectionAlongAxis

DirectPointSetUniformGridPattern 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

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

DirectPointSetUniformGridPattern minBound(int coordIndex)

Description copied from interface: Pattern

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. The number of dimensions in the resulting 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₀, p₁, ..., 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 uniform-grid 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 UniformGridPattern.lowerSurface(int); but if the figure, described by this pattern, contains some "holes", the result of this method contains fewer points than UniformGridPattern.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.

Specified by:

minBound in interface Pattern

Specified by:

minBound in interface UniformGridPattern

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

DirectPointSetUniformGridPattern maxBound(int coordIndex)

Description copied from interface: Pattern

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. The number of dimensions in the resulting 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₀, p₁, ..., 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 uniform-grid 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 UniformGridPattern.upperSurface(int); but if the figure, described by this pattern, contains some "holes", the result of this method contains fewer points than UniformGridPattern.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.

Specified by:

maxBound in interface Pattern

Specified by:

maxBound in interface UniformGridPattern

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)

gridIndexPattern

DirectPointSetUniformGridPattern 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

DirectPointSetUniformGridPattern 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

DirectPointSetUniformGridPattern 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

DirectPointSetUniformGridPattern 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.