public class RegularPolygon
extends java.lang.Object
PolygonOrientation
. The vertex coordinates of all polygons
are symmetrical across the vertical axis, and those of polygons with an even number of sides
are also symmetrical across the horizontal axis.
Upon construction, RegularPolygon
calculates the radii of the inscribed and
circumscribed circles, the coordinates of all vertices, and the minimum bounding rectangle.
All of these values are immutable once defined. Methods that seem to change the side length
of a given RegularPolygon
return a new instance instead.
Modifier and Type | Field and Description |
---|---|
RectD |
bounds
The bounding
RectD circumscribed around the RegularPolygon . |
int |
connectivity
The maximum number of neighbors for the
RegularPolygon . |
boolean |
hasTopIndex
Indicates whether index zero within
connectivity is topmost. |
double |
innerRadius
The radius of the circle inscribed within the
RegularPolygon . |
double |
length
The length of each side of the
RegularPolygon . |
PolygonOrientation |
orientation
The orientation of the
RegularPolygon . |
double |
outerRadius
The radius of the circle circumscribed around the
RegularPolygon . |
int |
sides
The number of sides of the
RegularPolygon . |
boolean |
vertexNeighbors
Indicates whether
RegularPolygon instances that share only a common vertex
are considered neighbors. |
PointD[] |
vertices
The
PointD coordinates of all vertices of the RegularPolygon . |
Constructor and Description |
---|
RegularPolygon(double length,
int sides,
PolygonOrientation orientation)
Creates a
RegularPolygon with the specified side length, number of sides, and orientation. |
RegularPolygon(double length,
int sides,
PolygonOrientation orientation,
boolean vertexNeighbors)
Creates a
RegularPolygon with the specified side length, number of sides, and orientation. |
Modifier and Type | Method and Description |
---|---|
int |
angleToIndex(double angle)
Converts the specified central angle to the index of the corresponding edge or vertex.
|
RegularPolygon |
circumscribe(double radius)
Creates a similar
RegularPolygon that is circumscribed around the specified circle. |
RegularPolygon |
circumscribe(double width,
double height)
Creates a similar
RegularPolygon that is circumscribed around the specified rectangle. |
int |
compassToIndex(Compass compass)
Converts the specified
Compass direction to the corresponding edge or vertex index. |
double |
indexToAngle(int index)
Converts the specified edge or vertex index to the corresponding central angle.
|
Compass |
indexToCompass(int index)
Converts the specified edge or vertex index to the corresponding
Compass direction. |
RegularPolygon |
inflate(double delta)
Creates a similar
RegularPolygon that is inflated by the specified radius. |
RegularPolygon |
inscribe(double radius)
Creates a similar
RegularPolygon that is inscribed in the specified circle. |
RegularPolygon |
inscribe(double width,
double height)
Creates a similar
RegularPolygon that is inscribed in the specified rectangle. |
int |
opposingIndex(int index)
Determines the index of the edge or vertex opposite to that with the specified index.
|
RegularPolygon |
resize(double length)
Creates a similar
RegularPolygon with the specified side length. |
public final RectD bounds
RectD
circumscribed around the RegularPolygon
.
All coordinates are relative to the center of the RegularPolygon
. The RectD
is horizontally centered on the RegularPolygon
, and also vertically centered for
an even number of sides
. Both RectD.min
coordinates are always negative,
and both RectD.max
coordinates are always positive.public final int connectivity
RegularPolygon
.
Equals sides
if #vertexNeighbors
is false
, else twice
that number. Applies to regular grids of adjacent identical RegularPolygon
instances, such as the ones represented by PolygonGrid
.public final boolean hasTopIndex
connectivity
is topmost.
true
if index zero within the connectivity
range corresponds to the
topmost edge or vertex of the RegularPolygon
; false
if this index
corresponds to the edge to the right of the topmost vertex.
hasTopIndex
is true
if one of the following conditions holds:
vertexNeighbors
is true
orientation
is PolygonOrientation.ON_EDGE
, and sides
is evenorientation
is PolygonOrientation.ON_VERTEX
, and sides
is oddpublic final double innerRadius
RegularPolygon
.
Always greater than zero and smaller than outerRadius
.public final double length
RegularPolygon
.
Always greater than zero.public final PolygonOrientation orientation
RegularPolygon
.
Never null
.public final double outerRadius
RegularPolygon
.
Always greater than zero and greater than innerRadius
.public final int sides
RegularPolygon
.
Always greater than or equal to three.public final boolean vertexNeighbors
RegularPolygon
instances that share only a common vertex
are considered neighbors.
Applies to regular grids of adjacent identical RegularPolygon
instances,
such as the ones represented by PolygonGrid
. Always false
if
sides
exceeds four, as inner angle of more than 90° prevent adjacent
instances from sharing a vertex without also sharing an edge.
RegularPolygon
instances that share a common edge are always considered
neighbors. The maximum number of shared edges, and possibly vertices, equals
sides
. vertexNeighbors
and sides
together determine
connectivity
which in turn determines the index range used by
angleToIndex(double)
and indexToAngle(int)
.
public final PointD[] vertices
PointD
coordinates of all vertices of the RegularPolygon
.
Always contains sides
elements. Starts with the topmost vertex or with the
right-hand one of two topmost vertices, and continues clockwise.
All coordinates are relative to the center of the RegularPolygon
.
The first element always has a negative PointD.y
coordinate.
public RegularPolygon(double length, int sides, PolygonOrientation orientation)
RegularPolygon
with the specified side length, number of sides, and orientation.
vertexNeighbors
is set to false
.length
- the length of each side of the RegularPolygon
sides
- the number of sides of the RegularPolygon
orientation
- the orientation of the RegularPolygon
java.lang.IllegalArgumentException
- if length
is equal to or less than zero,
or sides
is less than three, or orientation
is unknownjava.lang.NullPointerException
- if orientation
is null
public RegularPolygon(double length, int sides, PolygonOrientation orientation, boolean vertexNeighbors)
RegularPolygon
with the specified side length, number of sides, and orientation.length
- the length of each side of the RegularPolygon
sides
- the number of sides of the RegularPolygon
orientation
- the orientation of the RegularPolygon
vertexNeighbors
- true
if RegularPolygon
instances that share only
a common vertex are considered neighbors, else false
java.lang.IllegalArgumentException
- if length
is equal to or less than zero,
or sides
is less than three, or vertexNeighbors
is true
and sides
is greater than four, or orientation
is unknownjava.lang.NullPointerException
- if orientation
is null
public int angleToIndex(double angle)
angle
is measured from the center of the RegularPolygon
,
and increases clockwise from the right-hand side of the x-axis.
If vertexNeighbors
is false
, the returned index enumerates all edges
in clockwise direction. Counting starts at the topmost edge if hasTopIndex
is
true
, and with the edge to the right of the topmost vertex otherwise.
If vertexNeighbors
is true
, the returned index enumerates all edges
and vertices in an alternating sequence. Counting starts with the topmost edge if
orientation
equals PolygonOrientation.ON_EDGE
and with the topmost vertex
otherwise, continuing clockwise.
Valid indices range from zero to connectivity
less one. The 360 degrees
of a full rotation around the central point are evenly divided among this range so that
each index corresponds to an equal arc. If vertexNeighbors
is true
,
the arcs that are mapped to edge indices cover only the central half of each edge. The
arcs covering the outer parts are mapped to vertex indices instead.
angle
- the central angle to convert, in degrees. Taken modulo 360°
and may therefore lie outside the interval [0, 360)angle
public RegularPolygon circumscribe(double radius)
RegularPolygon
that is circumscribed around the specified circle.
Returns the current instance if innerRadius
already equals radius
.radius
- the radius of the circle around which to circumscribe the RegularPolygon
RegularPolygon
whose innerRadius
equals radius
and which is otherwise identical with the current instancejava.lang.IllegalArgumentException
- if radius
is equal to or less than zeropublic RegularPolygon circumscribe(double width, double height)
RegularPolygon
that is circumscribed around the specified rectangle.
Returns exact results for triangles and squares only. For other polygons, the returned
RegularPolygon
is an approximation that includes some excess space around an
inscribed rectangle with the specified width
and height
.width
- the width of the rectangle around which to circumscribe the RegularPolygon
height
- the width of the rectangle around which to circumscribe the RegularPolygon
RegularPolygon
whose bounds
completely cover both width
and height
, and which is otherwise identical with the current instancejava.lang.IllegalArgumentException
- if width
or height
is equal to or less than zeropublic int compassToIndex(Compass compass)
Compass
direction to the corresponding edge or vertex index.
Returns the result of Compass.degrees()
for compass
, less 90 degrees.
See angleToIndex(double)
for an explanation of index values.compass
- the Compass
direction to convertcompass
java.lang.NullPointerException
- if compass
is null
public double indexToAngle(int index)
RegularPolygon
and increases clockwise from the right-hand side of the x-axis.
This value represents the angle from the central point to the indicated vertex,
or to the middle of the indicated edge.
If vertexNeighbors
is false
, the specified index
enumerates
all edges in clockwise direction. Counting starts at the topmost edge if hasTopIndex
is true
, and with the edge to the right of the topmost vertex otherwise.
If vertexNeighbors
is true
, the specified index
enumerates
all edges and vertices in an alternating sequence. Counting starts with the topmost edge
for PolygonOrientation.ON_EDGE
orientation and with the topmost vertex otherwise,
continuing clockwise.
index
- the zero-based index of an edge or vertex. Taken modulo connectivity
and may therefore be negative or greater than the maximum indexindex
public Compass indexToCompass(int index)
Compass
direction.
First adds 90° to the result of indexToAngle(int)
for the specified index
,
and then returns the result of Angle.degreesToCompass(double)
for that angle.
See indexToAngle(int)
for an explanation of index values.index
- the zero-based index of an edge or vertex. Taken modulo connectivity
and may therefore be negative or greater than the maximum indexCompass
direction closest to the edge or vertex with the specified index
public RegularPolygon inflate(double delta)
RegularPolygon
that is inflated by the specified radius.
Returns the current instance if delta
equals zero. Otherwise, adds delta
(which may be negative) to outerRadius
. The new length
changes by the
same ratio as the new outerRadius
.delta
- the amount by which to inflate the outerRadius
of the RegularPolygon
RegularPolygon
whose outerRadius
is inflated by delta
and which is otherwise identical with the current instancejava.lang.IllegalArgumentException
- if delta
is equal to or less than the negative
value of outerRadius
public RegularPolygon inscribe(double radius)
RegularPolygon
that is inscribed in the specified circle.
Returns the current instance if outerRadius
already equals radius
.radius
- the radius of the circle in which to inscribe the RegularPolygon
RegularPolygon
whose outerRadius
equals radius
and which is otherwise identical with the current instancejava.lang.IllegalArgumentException
- if radius
is equal to or less than zeropublic RegularPolygon inscribe(double width, double height)
RegularPolygon
that is inscribed in the specified rectangle.
Returns the current instance if the extensions of bounds
already equal both
width
and height
.width
- the width of the rectangle in which to inscribe the RegularPolygon
height
- the width of the rectangle in which to inscribe the RegularPolygon
RegularPolygon
whose bounds
exactly match either width
or height
without exceeding the other dimension, and which is otherwise
identical with the current instancejava.lang.IllegalArgumentException
- if width
or height
is equal to or less than zeropublic int opposingIndex(int index)
indexToAngle(int)
for an explanation of index values.index
- the zero-based index of an edge or vertex. Taken modulo connectivity
and may therefore be negative or greater than the maximum indexindex
java.lang.IllegalStateException
- if connectivity
is odd, as opposing indices
exist only if the total number of indices is evenpublic RegularPolygon resize(double length)
RegularPolygon
with the specified side length.
Returns the current instance if length
already equals the specified length
.length
- the new length
for the RegularPolygon
RegularPolygon
whose length
equals length
and which is otherwise identical with the current instancejava.lang.IllegalArgumentException
- if length
is equal to or less than zero