---
title: "Polygon"
description: "A closed polygon defined by a list of vertices."
canonical_url: "https://www.rosette.dev/docs/api-reference/Polygon"
markdown_url: "https://www.rosette.dev/docs/api-reference/Polygon.md"
source_url: "https://github.com/PreFab-Photonics/rosette/blob/f086d7670645fd36c05362d696d442a2b2e74850/www/content/docs/api-reference/Polygon.mdx"
docs_channel: "main"
docs_revision: "f086d7670645fd36c05362d696d442a2b2e74850"
---

# Polygon

A closed polygon defined by a list of vertices.

Polygons are the primary geometry primitive for layout. They represent
filled shapes on a layer -- waveguides, pads, gratings, and any other
structure. Polygons are immutable; all transformation methods return new
Polygon instances.

A polygon requires at least three vertices, and every coordinate must be
finite. This is a local numeric and cardinality invariant, not a topology
check: repeated vertices, zero-area polygons, and self-intersecting polygons
remain representable. Invalid Python inputs raise `ValueError`.

```python
# Rectangle from origin
rect = Polygon.rect(Point.origin(), 10, 5)

# Centered rectangle
square = Polygon.rect_centered(Point(50, 50), 20, 20)

# Regular hexagon
hex = Polygon.regular(Point(0, 0), radius=10, sides=6)

# Custom shape
tri = Polygon([Point(0, 0), Point(10, 0), Point(5, 8)])
```

## Static constructors



### `rect`

```python
rect(origin, width, height) -> Polygon
```

Create a rectangle with one corner at `origin`, extending in +X and +Y.



- **`origin`** (`Point`)

  Bottom-left corner of the rectangle.





- **`width`** (`float`)

  Width along the X axis.





- **`height`** (`float`)

  Height along the Y axis.





**Returns:** `Polygon`





### `rect_centered`

```python
rect_centered(center, width, height) -> Polygon
```

Create a rectangle centered on a point.



- **`center`** (`Point`)

  Center of the rectangle.





- **`width`** (`float`)

  Width along the X axis.





- **`height`** (`float`)

  Height along the Y axis.





**Returns:** `Polygon`





### `regular`

```python
regular(center, radius, sides) -> Polygon
```

Create a regular polygon (equilateral triangle, square, hexagon, etc.)
inscribed in a circle.



- **`center`** (`Point`)

  Center of the polygon.





- **`radius`** (`float`)

  Circumscribed radius (distance from center to each vertex).





- **`sides`** (`int`)

  Number of sides.





**Returns:** `Polygon`



## Methods



### `__init__`

```python
__init__(vertices) -> None
```

Create a polygon from a list of vertices. The polygon is automatically
closed (you do not need to repeat the first vertex).



- **`vertices`** (`list[Point]`)

  Ordered list of at least three finite vertex points. Repeated vertices,
  zero-area rings, and self-intersections are accepted.





**Returns:** `None`





### `vertices`

```python
vertices() -> list[Point]
```

Return the list of vertices.



**Returns:** `list[Point]`





### `area`

```python
area() -> float
```

Compute the absolute area of the polygon. The result is non-negative and does
not depend on clockwise or counter-clockwise vertex winding.



**Returns:** `float`





### `centroid`

```python
centroid() -> Point
```

Compute the centroid (geometric center of mass) of the polygon.



**Returns:** `Point`





### `bbox`

```python
bbox() -> BBox
```

Compute the axis-aligned bounding box of the polygon.



**Returns:** `BBox`



### Transformations

Transformation inputs and resulting vertex coordinates must be finite. A
translation, rotation, or scale that would produce a non-finite coordinate
raises `ValueError` instead of returning invalid geometry.



### `translate`

```python
translate(v) -> Polygon
```

Return a new polygon translated by a vector.



- **`v`** (`Vector2`)

  Translation vector.





**Returns:** `Polygon`





### `rotate`

```python
rotate(angle_deg) -> Polygon
```

Rotate the polygon around the origin.



- **`angle_deg`** (`float`)

  Rotation angle in degrees (counter-clockwise).





**Returns:** `Polygon`





### `rotate_around`

```python
rotate_around(center, angle_deg) -> Polygon
```

Rotate the polygon around an arbitrary center point.



- **`center`** (`Point`)

  Center of rotation.





- **`angle_deg`** (`float`)

  Rotation angle in degrees (counter-clockwise).





**Returns:** `Polygon`





### `scale`

```python
scale(sx, sy) -> Polygon
```

Scale the polygon by independent factors along each axis.



- **`sx`** (`float`)

  Scale factor along the X axis.





- **`sy`** (`float`)

  Scale factor along the Y axis.





**Returns:** `Polygon`





### `mirror_x`

```python
mirror_x() -> Polygon
```

Mirror the polygon across the X axis (flip Y coordinates).



**Returns:** `Polygon`





### `mirror_y`

```python
mirror_y() -> Polygon
```

Mirror the polygon across the Y axis (flip X coordinates).



**Returns:** `Polygon`



### Boolean operations

Boolean operations combine or cut polygons. All four methods return a
`list[Polygon]` because a single operation can produce multiple disjoint
pieces. Holes created by subtraction are handled via keyholing
(a zero-width bridge connecting the hole to the exterior), keeping every
result a single-ring polygon compatible with GDS-II.

```python
a = Polygon.rect(Point(0, 0), 10, 10)
b = Polygon.rect(Point(5, 0), 10, 10)

merged = a.union(b)        # combined outline
diff   = a.subtract(b)     # a minus overlap
common = a.intersect(b)    # overlap only
sym    = a.xor(b)          # either but not both
```



### `union`

```python
union(other) -> list[Polygon]
```

Compute the union (merge) of this polygon with another. Overlapping
regions are merged into a single outline.



- **`other`** (`Polygon`)

  The polygon to union with.





**Returns:** `list[Polygon]`





### `subtract`

```python
subtract(other) -> list[Polygon]
```

Subtract another polygon from this one. Returns the area of this polygon
that does not overlap with `other`. If `other` is fully contained, the
result is a keyholed polygon with a zero-width bridge.



- **`other`** (`Polygon`)

  The polygon to subtract.





**Returns:** `list[Polygon]`





### `intersect`

```python
intersect(other) -> list[Polygon]
```

Compute the intersection of this polygon with another. Returns the
overlapping area shared by both inputs. Empty list if no overlap.



- **`other`** (`Polygon`)

  The polygon to intersect with.





**Returns:** `list[Polygon]`





### `xor`

```python
xor(other) -> list[Polygon]
```

Compute the symmetric difference (XOR) of this polygon with another.
Returns the area in either polygon but not both. Empty list if
polygons are identical.



- **`other`** (`Polygon`)

  The polygon to XOR with.





**Returns:** `list[Polygon]`



## Supported operations

**Length**: `len(polygon)` returns the number of vertices.

```python
rect = Polygon.rect(Point.origin(), 10, 5)
len(rect)  # 4
```

**Iteration**: Polygons support iteration over their vertices.

```python
for vertex in polygon:
    print(vertex.x, vertex.y)
```