RegularPolygon (tektosyne API)

java.lang.Object
- org.kynosarges.tektosyne.geometry.RegularPolygon

```
public class RegularPolygon
extends java.lang.Object
```
Represents a regular polygon. Defines a regular polygon with three or more sides of a given length, and with one of the orientations defined by 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.

Field Summary

Fields
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 Summary

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

Method Summary

All Methods Instance Methods Concrete Methods
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.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - bounds
```
public final RectD bounds
```
    The bounding 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.
  - connectivity
```
public final int connectivity
```
    The maximum number of neighbors for the 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.
  - hasTopIndex
```
public final boolean hasTopIndex
```
    Indicates whether index zero within 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 even
    - orientation is PolygonOrientation.ON_VERTEX, and sides is odd
  - innerRadius
```
public final double innerRadius
```
    The radius of the circle inscribed within the RegularPolygon. Always greater than zero and smaller than outerRadius.
  - length
```
public final double length
```
    The length of each side of the RegularPolygon. Always greater than zero.
  - orientation
```
public final PolygonOrientation orientation
```
    The orientation of the RegularPolygon. Never null.
  - outerRadius
```
public final double outerRadius
```
    The radius of the circle circumscribed around the RegularPolygon. Always greater than zero and greater than innerRadius.
  - sides
```
public final int sides
```
    The number of sides of the RegularPolygon. Always greater than or equal to three.
  - vertexNeighbors
```
public final boolean vertexNeighbors
```
    Indicates whether 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).
  - vertices
```
public final PointD[] vertices
```
    The 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.
- Constructor Detail
  - RegularPolygon
```
public RegularPolygon(double length,
                      int sides,
                      PolygonOrientation orientation)
```
    Creates a RegularPolygon with the specified side length, number of sides, and orientation. vertexNeighbors is set to false.
    
    Parameters:
    
    length - the length of each side of the RegularPolygon
    
    sides - the number of sides of the RegularPolygon
    
    orientation - the orientation of the RegularPolygon
    
    Throws:
    
    java.lang.IllegalArgumentException - if length is equal to or less than zero, or sides is less than three, or orientation is unknown
    
    java.lang.NullPointerException - if orientation is null
  - RegularPolygon
```
public RegularPolygon(double length,
                      int sides,
                      PolygonOrientation orientation,
                      boolean vertexNeighbors)
```
    Creates a RegularPolygon with the specified side length, number of sides, and orientation.
    
    Parameters:
    
    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
    
    Throws:
    
    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 unknown
    
    java.lang.NullPointerException - if orientation is null
- Method Detail
  - angleToIndex
```
public int angleToIndex(double angle)
```
    Converts the specified central angle to the index of the corresponding edge or vertex. The specified 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.
    
    Parameters:
    
    angle - the central angle to convert, in degrees. Taken modulo 360° and may therefore lie outside the interval [0, 360)
    
    Returns:
    
    the zero-based index of the edge or vertex at angle
  - circumscribe
```
public RegularPolygon circumscribe(double radius)
```
    Creates a similar RegularPolygon that is circumscribed around the specified circle. Returns the current instance if innerRadius already equals radius.
    
    Parameters:
    
    radius - the radius of the circle around which to circumscribe the RegularPolygon
    
    Returns:
    
    a RegularPolygon whose innerRadius equals radius and which is otherwise identical with the current instance
    
    Throws:
    
    java.lang.IllegalArgumentException - if radius is equal to or less than zero
  - circumscribe
```
public RegularPolygon circumscribe(double width,
                                   double height)
```
    Creates a similar 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.
    
    Parameters:
    
    width - the width of the rectangle around which to circumscribe the RegularPolygon
    
    height - the width of the rectangle around which to circumscribe the RegularPolygon
    
    Returns:
    
    a RegularPolygon whose bounds completely cover both width and height, and which is otherwise identical with the current instance
    
    Throws:
    
    java.lang.IllegalArgumentException - if width or height is equal to or less than zero
  - compassToIndex
```
public int compassToIndex(Compass compass)
```
    Converts the specified 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.
    
    Parameters:
    
    compass - the Compass direction to convert
    
    Returns:
    
    the zero-based index of the edge or vertex closest to compass
    
    Throws:
    
    java.lang.NullPointerException - if compass is null
  - indexToAngle
```
public double indexToAngle(int index)
```
    Converts the specified edge or vertex index to the corresponding central angle. Always returns a value within [0, 360) which is measured from the center of the 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.
    
    Parameters:
    
    index - the zero-based index of an edge or vertex. Taken modulo connectivity and may therefore be negative or greater than the maximum index
    
    Returns:
    
    the central angle, in degrees, of the edge or vertex with the specified index
  - indexToCompass
```
public Compass indexToCompass(int index)
```
    Converts the specified edge or vertex index to the corresponding 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.
    
    Parameters:
    
    index - the zero-based index of an edge or vertex. Taken modulo connectivity and may therefore be negative or greater than the maximum index
    
    Returns:
    
    the Compass direction closest to the edge or vertex with the specified index
  - inflate
```
public RegularPolygon inflate(double delta)
```
    Creates a similar 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.
    
    Parameters:
    
    delta - the amount by which to inflate the outerRadius of the RegularPolygon
    
    Returns:
    
    a RegularPolygon whose outerRadius is inflated by delta and which is otherwise identical with the current instance
    
    Throws:
    
    java.lang.IllegalArgumentException - if delta is equal to or less than the negative value of outerRadius
  - inscribe
```
public RegularPolygon inscribe(double radius)
```
    Creates a similar RegularPolygon that is inscribed in the specified circle. Returns the current instance if outerRadius already equals radius.
    
    Parameters:
    
    radius - the radius of the circle in which to inscribe the RegularPolygon
    
    Returns:
    
    a RegularPolygon whose outerRadius equals radius and which is otherwise identical with the current instance
    
    Throws:
    
    java.lang.IllegalArgumentException - if radius is equal to or less than zero
  - inscribe
```
public RegularPolygon inscribe(double width,
                               double height)
```
    Creates a similar RegularPolygon that is inscribed in the specified rectangle. Returns the current instance if the extensions of bounds already equal both width and height.
    
    Parameters:
    
    width - the width of the rectangle in which to inscribe the RegularPolygon
    
    height - the width of the rectangle in which to inscribe the RegularPolygon
    
    Returns:
    
    a RegularPolygon whose bounds exactly match either width or height without exceeding the other dimension, and which is otherwise identical with the current instance
    
    Throws:
    
    java.lang.IllegalArgumentException - if width or height is equal to or less than zero
  - opposingIndex
```
public int opposingIndex(int index)
```
    Determines the index of the edge or vertex opposite to that with the specified index. See indexToAngle(int) for an explanation of index values.
    
    Parameters:
    
    index - the zero-based index of an edge or vertex. Taken modulo connectivity and may therefore be negative or greater than the maximum index
    
    Returns:
    
    the zero-based index of the edge or vertex opposite index
    
    Throws:
    
    java.lang.IllegalStateException - if connectivity is odd, as opposing indices exist only if the total number of indices is even
  - resize
```
public RegularPolygon resize(double length)
```
    Creates a similar RegularPolygon with the specified side length. Returns the current instance if length already equals the specified length.
    
    Parameters:
    
    length - the new length for the RegularPolygon
    
    Returns:
    
    a RegularPolygon whose length equals length and which is otherwise identical with the current instance
    
    Throws:
    
    java.lang.IllegalArgumentException - if length is equal to or less than zero

Class RegularPolygon

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

bounds

connectivity

hasTopIndex

innerRadius

length

orientation

outerRadius

sides

vertexNeighbors

vertices

Constructor Detail

RegularPolygon

RegularPolygon

Method Detail

angleToIndex

circumscribe

circumscribe

compassToIndex

indexToAngle

indexToCompass

inflate

inscribe

inscribe

opposingIndex

resize