public abstract static class Matrices.Region
extends java.lang.Object
Region in ndimensional space. More precisely, this class defines a random set of points
with integer coordinates in ndimensional space.
Though some kinds of regions are defined in terms of real coordinates,
this class is useful for processing only integer points belonging to the region.
This class is designed for copying/filling regions in AlgART matrices
by
Matrices.copyRegion(ArrayContext, Matrix, Matrix, net.algart.arrays.Matrices.Region, long...)
,Matrices.copyRegion(ArrayContext, Matrix, Matrix, net.algart.arrays.Matrices.Region, long[], Object)
andMatrices.fillRegion(ArrayContext, Matrix, net.algart.arrays.Matrices.Region, Object)
methods, where noninteger coordinates are needless.
This class is abstract and describes the region (set of points) by the only one simple abstract method
contains(long... coordinates)
coordinate ranges
:
such ranges that coordinates of all region points guaranteedly belong to them.
However, the region, constructed by this way, provides low performance of
Matrices.copyRegion
/ Matrices.fillRegion
methods,
because the only way to process it is checking all points separately by
contains(long...)
sectionAtLastCoordinate(long sectionCoordinateValue)
contains(long...)
An idea of this method is the following. It allows to represent the sectionAtLastCoordinate
for all possible values of its argument sectionCoordinateValue.
Then every Hyperparallelepiped
), which can be processes very quickly.
If an inheritor correctly implements sectionAtLastCoordinate
and if this method does not use contains(long...)
Region.sectionAtLastCoordinate
, then the inheritor
is allowed not to implement contains(long...)
isContainsSupported()
method and return false by it.
In this case, contains(long...)
This class can represent an empty region (containing no points). The number of dimensions of the range is always positive (1, 2, ...).
This package offers the following implementations of the regions:
Matrices.Hyperparallelepiped
: the simplest possible region (a segment in Matrices.ConvexHyperpolyhedron
: an intersection of several Matrices.Simplex
: the simplest kind of Matrices.Polygon2D
: a random Note that all region types are always restricted by the hyperparallelepiped, defined by the
coordinate ranges
, so a region cannot be infinite.
Also note: this class and its inheritors from this package do not implement own equals and hashCode methods. So, this class does not provide a mechanism for comparing different regions.
Inheritors of this abstract class are usually immutable and always threadsafe: all methods of this class may be freely used while simultaneous accessing the same instance from several threads. All inheritors of this class from this package are immutable.
Modifier  Constructor and Description 

protected 
Region(IRange[] coordRanges)
Creates new instance of this class.

Modifier and Type  Method and Description 

protected boolean 
checkSectionAtLastCoordinate(long sectionCoordinateValue)
Returns true if and only the specified coordinate value lies inside the corresponding
coordinate range . 
abstract boolean 
contains(long... coordinates)
Returns true if and only if the point with the specified integer coordinates
belongs to this region.

IRange 
coordRange(int coordIndex)
Returns the coordinate range #coordIndex.

IRange[] 
coordRanges()
Returns the coordinate ranges, passed to the constructor.

static Matrices.ConvexHyperpolyhedron 
getConvexHyperpolyhedron(double[] a,
double[] b,
IRange... coordRanges)
Creates ndimensional
convex hyperpolyhedron ,
which is an intersection of m 
static Matrices.Hyperparallelepiped 
getHyperparallelepiped(IRange... coordRanges)
Creates ndimensional
hyperparallelepiped with edges,
parallel to coordinate axes, described by the given ranges of coordinates. 
static Matrices.Hyperparallelepiped 
getParallelepiped3D(IRange xRange,
IRange yRange,
IRange zRange)
Creates 3dimensional parallelepiped with edges, parallel to coordinate axes,
described by the given ranges of coordinates.

static Matrices.Polygon2D 
getPolygon2D(double[][] vertices)
Creates
2dimensional polygon with the specified coordinates of vertices. 
static Matrices.Hyperparallelepiped 
getRectangle2D(IRange xRange,
IRange yRange)
Creates 2dimensional rectangle with sides, parallel to coordinate axes,
described by the given ranges of coordinates.

static Matrices.Hyperparallelepiped 
getSegment(IRange xRange)
Creates 1dimensional segment, described by the given range.

static Matrices.Simplex 
getSimplex(double[][] vertices)
Creates ndimensional
simplex with the specified coordinates of vertices. 
static Matrices.Simplex 
getTetrahedron3D(double x1,
double y1,
double z1,
double x2,
double y2,
double z2,
double x3,
double y3,
double z3,
double x4,
double y4,
double z4)
Creates 3dimensional tetrahedron with the specified coordinates of vertices.

static Matrices.Simplex 
getTriangle2D(double x1,
double y1,
double x2,
double y2,
double x3,
double y3)
Creates 2dimensional triangle with the specified coordinates of vertices.

boolean 
isContainsSupported()
Indicates whether the method
contains(long...) in this class works correctly. 
boolean 
isRectangular()
Returns true if this region is rectangular, that is if it contains the same set of
integer points (points with integer coordinates) as some
hyperparallelepiped . 
int 
n()
Returns the number of dimensions of this region.

Matrices.Region[] 
sectionAtLastCoordinate(long sectionCoordinateValue)
Finds the intersection of this region with the hyperplane, described by the equation
x_{n−1}=sectionCoordinateValue,
and returns this intersection as an array of

protected Region(IRange[] coordRanges)
The passed coordRanges array is cloned by this constructor: no references to it are maintained by the created object.
coordRanges
 the ranges that guaranteedly contain coordinates of all points of this region
(they will be returned by coordRanges()
method).java.lang.NullPointerException
 if the coordRanges array some of its elements is null.java.lang.IllegalArgumentException
 if the passed array is empty (coordRanges.length==0).public static Matrices.Hyperparallelepiped getSegment(IRange xRange)
getHyperparallelepiped(xRange)
xRange
 the range of the only coordinate of all points of the segment.java.lang.NullPointerException
 if the argument is null.public static Matrices.Hyperparallelepiped getRectangle2D(IRange xRange, IRange yRange)
getHyperparallelepiped(xRange, yRange)
Note: an equivalent region can be constructed by getPolygon2D(double[][] vertices)
method.
But the region, constructed by this method, is processed little faster.
xRange
 the xprojection of the rectangle.yRange
 the yprojection of the rectangle.java.lang.NullPointerException
 if one of the arguments is null.public static Matrices.Hyperparallelepiped getParallelepiped3D(IRange xRange, IRange yRange, IRange zRange)
getHyperparallelepiped(xRange, yRange, zRange)
xRange
 the xprojection of the rectangle.yRange
 the yprojection of the rectangle.zRange
 the zprojection of the rectangle.java.lang.NullPointerException
 if one of the arguments is null.public static Matrices.Hyperparallelepiped getHyperparallelepiped(IRange... coordRanges)
hyperparallelepiped
with edges,
parallel to coordinate axes, described by the given ranges of coordinates.
More precisely, the returned region contains all such points
coordRanges[0].min()
≤ x_{0} ≤ coordRanges[0].max()
,
coordRanges[1].min()
≤ x_{1} ≤ coordRanges[1].max()
,
...,
coordRanges[n1].min()
≤ x_{n−1} ≤ coordRanges[n1].max()
.
The number n of dimensions of the created region is equal to coordRanges.length.
The passed coordRanges array is cloned by this method: no references to it are maintained by the created object.
coordRanges
 the ranges of coordinates of the hyperparallelepiped.java.lang.NullPointerException
 if the coordRanges array some of its elements is null.java.lang.IllegalArgumentException
 if the passed array is empty (coordRanges.length==0).public static Matrices.Simplex getTriangle2D(double x1, double y1, double x2, double y2, double x3, double y3)
getSimplex
(new double[][] {{x1,y1},{x2,y2},{x3,y3}})The specified vertices must not lie in the same straight line.
Note: an equivalent region can be constructed by getPolygon2D(double[][] vertices)
method.
But the region, constructed by this method, is processed little faster.
On the other hand, getPolygon2D
method works correcly even
if the vertices lie in the same straight line.
All calculations while building the triangle are performed in strictfp mode, so the results are absolutely identical on all platforms.
x1
 the xcoordinate of the 1st vertex.y1
 the ycoordinate of the 1st vertex.x2
 the xcoordinate of the 2nd vertex.y2
 the ycoordinate of the 2nd vertex.x3
 the xcoordinate of the 3rd vertex.y3
 the ycoordinate of the 3rd vertex.DegeneratedSimplexException
 if all vertices lies in the same straight line
(as it is detected by analysing the coordinates
via calculations with standard Java double numbers).public static Matrices.Simplex getTetrahedron3D(double x1, double y1, double z1, double x2, double y2, double z2, double x3, double y3, double z3, double x4, double y4, double z4)
getSimplex
(new double[][]
{{x1,y1,z1},{x2,y2,z2},{x3,y3,z3},{x4,y4,z4}})The specified vertices must not lie in the same plane.
All calculations while building the tetrahedron are performed in strictfp mode, so the results are absolutely identical on all platforms.
x1
 the xcoordinate of the 1st vertex.y1
 the ycoordinate of the 1st vertex.z1
 the zcoordinate of the 1st vertex.x2
 the xcoordinate of the 2nd vertex.y2
 the ycoordinate of the 2nd vertex.z2
 the zcoordinate of the 2nd vertex.x3
 the xcoordinate of the 3rd vertex.y3
 the ycoordinate of the 3rd vertex.z3
 the zcoordinate of the 3rd vertex.x4
 the xcoordinate of the 4th vertex.y4
 the ycoordinate of the 4th vertex.z4
 the zcoordinate of the 4th vertex.DegeneratedSimplexException
 if all vertices lies in the same plane
(as it is detected by analysing the coordinates
via calculations with standard Java double numbers).public static Matrices.Simplex getSimplex(double[][] vertices)
simplex
with the specified coordinates of vertices.
More precisely, this method creates a simplex — the simplest ndimensional hyperpolyhedron
with The number n of dimensions of the created region is equal to vertices[k].length; this length must be same for all k. The number of vertices vertices.length must be equal to n+1.
The points, lying precisely in the (hyper)facets of the simplex (in particular, the vertices), belong to the resulting region.
The created region is defined in terms of real coordinates, but only integer points belonging to this region are really processed by methods of this package.
The passed vertices array is deeply cloned by this method: no references to it or its elements are maintained by the created object.
The specified vertices must not lie in the same (n−1)dimensional hyperplane.
Note: this method allocates two Java double[] arrays containing n+1 and n*(n+1) elements. We do not recommend create simplexes with large number of dimensions: this method can work very slowly when n is greater than 6–7.
All calculations while building the simplex are performed in strictfp mode, so the results are absolutely identical on all platforms.
vertices
 coordinates of all vertices.java.lang.NullPointerException
 if the vertices array or some of its elements is null.java.lang.IllegalArgumentException
 if the vertices array or some of its elements is empty
(has zero length),
or if the length of some vertices[k] array is not equal to
vertices[0].length+1.DegeneratedSimplexException
 if all vertices lies in the same (n−1)dimensional
hyperplane (as it is detected by analysing the coordinates
via calculations with standard Java double numbers).public static Matrices.ConvexHyperpolyhedron getConvexHyperpolyhedron(double[] a, double[] b, IRange... coordRanges)
convex hyperpolyhedron
,
which is an intersection of m getHyperparallelepiped(IRange... coordRanges)
method with
the same coordRanges argument. Here a_{i}x means
the scalar product of the line #i of the matrix A, passed by the first argument,
and the vector of coordinates
The number n of dimensions of the created region is equal to coordRanges.length.
The points, lying precisely in the (hyper)facets of the hyperpolyhedron (in particular, the vertices), belong to the resulting region.
The created region is defined in terms of real coordinates, but only integer points belonging to this region are really processed by methods of this package.
The passed Java arrays are cloned by this method: no references to them are maintained by the created object.
a
 the matrix of coefficients of the left side of inequations, defining the halfspaces.b
 the values in the right side of inequations, defining the halfspaces.coordRanges
 the ranges of coordinates of the containing hyperparallelepiped.java.lang.NullPointerException
 if one of the arguments is null
or if some element of coordRanges array is null.java.lang.IllegalArgumentException
 if coordRanges.length==0,
or if a.length!=coordRanges.length*b.length.public static Matrices.Polygon2D getPolygon2D(double[][] vertices)
2dimensional polygon
with the specified coordinates of vertices.
More precisely, this method creates a polygon
with m=vertices.length vertices, where the vertex #k
(k=0,1,...,m−1)
has the coordinates The created polygon can be nonconvex and even selfintersecting. The vertices can be specified both in clockwise or in anticlockwise order. The points, lying precisely in the sides of the polygon (in particular, the vertices), belong to the resulting region.
The created region is defined in terms of real coordinates, but only integer points belonging to this region are really processed by methods of this package.
The passed vertices array is deeply cloned by this method: no references to it or its elements are maintained by the created object.
Note: this method allocates two Java double[] arrays containing m elements.
vertices
 coordinates of all vertices.java.lang.NullPointerException
 if the vertices array or some of its elements is null.java.lang.IllegalArgumentException
 if the vertices array or some of its elements is empty
(has zero length),
or if the length of some vertices[k] array is not 2.public final int n()
public final IRange[] coordRanges()
n()
.
For Matrices.Hyperparallelepiped
and Matrices.ConvexHyperpolyhedron
classes,
these ranges are the same as the corresponding argument of the instantiation methods
(getHyperparallelepiped(IRange...)
and
getConvexHyperpolyhedron(double[], double[], IRange...)
).
For Matrices.Simplex
and Matrices.Polygon2D
classes,
these ranges are calculated automatically as the minimal integer ranges, containing all vertices,
passed to the instantiation methods
(getSimplex(double[][])
and getPolygon2D(double[][])
).
The returned array is a clone of the internal array stored in this object.
public final IRange coordRange(int coordIndex)
coordRanges()
[coordIndex], but works faster.coordIndex
 the index of coordinate.java.lang.IndexOutOfBoundsException
 if coordIndex<0 or coordIndex>=n()
.public boolean isRectangular()
hyperparallelepiped
.
This method always returns false if this region is not rectangular,
but there is no guarantee that it returns true when it is rectangular.
This default implementation returns false.
In Matrices.Hyperparallelepiped
class this method returns true.
In all other inheritors of this class, implemented in this package, it returns false.
public abstract boolean contains(long... coordinates)
The coordinates must contain at least n()
elements.
It can contain more than n()
elements; then the extra elements will be ignored.
Warning! Some inheritors of this class does not provide correct implementation of this method.
In this case, isContainsSupported()
method returns false and this method throws
UnsupportedOperationException. So, you must always check the result of
isContainsSupported()
method before calling this one.
However, this method must be correctly implemented, if this region is a
n()
==1) and isRectangular()
method returns false.
Note: even if the inheritor does not provide correct implementation of this method,
it must always provide correct implementation of sectionAtLastCoordinate(long)
method.
coordinates
 the coordinates of the point: the first element is x, the second is y, ...java.lang.NullPointerException
 if the argument is null.java.lang.IndexOutOfBoundsException
 if the length of the passed array is less than n()
.java.lang.UnsupportedOperationException
 if the inheritor does not implement this operation.public boolean isContainsSupported()
contains(long...)
in this class works correctly.
You should use contains(long...)
method only
if this method returns true;
in other case, contains(long...)
throws UnsupportedOperationException.
This default implementation returns true.
So, if you prefer not to implement contains(long...)
method,
you must override this method and return false.
This method must return true if
n()
==1 && !isRectangular()
contains(long...)
method works correctly;
otherwise contains(long...)
method throws UnsupportedOperationException.public Matrices.Region[] sectionAtLastCoordinate(long sectionCoordinateValue)
This method must not be used if this region is n()
==1). In this case, it throws IllegalStateException.
This default implementation is based on contains(long...)
method, which is supposed
to be correctly implemented.
Note: it is possible (in some rare exotic cases), that the regions, returned by this method,
intersects with each other: some points will belong to 2 and more elements of the result.
In particular, it is possible for Matrices.Polygon2D
,
if some sides of the polygon lie exactly at the horizontal y=sectionCoordinateValue.
Implementations of this method in this packages, besides the implementation in
Matrices.Polygon2D
class, never return more than 1 region in the result.
You must override this method if you prefer not to implement contains(long...)
method
(isContainsSupported()
returns false). In this case, your implementation
must not call contains(long...)
method or
sectionAtLastCoordinate(long)
sectionCoordinateValue
 the value of the last coordinate.java.lang.IllegalStateException
 if this region is n()
==1).protected final boolean checkSectionAtLastCoordinate(long sectionCoordinateValue)
coordinate range
. In other words, returns the result of the following check:
coordRange
(n()
1).contains
(coordinateValue)n()
and throws
IllegalStateException if n()
==1.
This method is usually called at the beginning of sectionAtLastCoordinate(long)
method.
If it returns false, that method returns an empty array.
sectionCoordinateValue
 the value of the last coordinate.coordinate range
.java.lang.IllegalStateException
 if this region is n()
==1).