# Tilings

[Start here](https://pegmatite.dev/guide/start.md). Fetch this topic when a plate or face needs a grid of holes: honeycomb, square, triangle, stripe or Voronoi cells.

## Regular tilings

**Syntax:** **`honeycomb`** _diameter_ _strut_ [**`angle`** _degrees_] [**`rim`** _width_] **`in`** _area_

**Syntax:** **`squares`** _diameter_ _strut_ [**`angle`** _degrees_] [**`rim`** _width_] **`in`** _area_

**Syntax:** **`triangles`** _diameter_ _strut_ [**`angle`** _degrees_] [**`rim`** _width_] **`in`** _area_

**Syntax:** **`stripes`** _width_ _strut_ [**`angle`** _degrees_] [**`rim`** _width_] **`in`** _area_

A tiling is a shape: it lays cells over the area of the shape written after `in`, and is swept like any shape. Neighbouring cells are _strut_ apart, so subtracting a tiling from a plate leaves struts of that width.

```pegm
!@right 6
honeycomb 8 1.5 in rect 40 40 | extrude 3
squares 8 1.5 in rect 40 40 | extrude 3
triangles 8 1.5 in rect 40 40 | extrude 3
stripes 4 2 in rect 40 40 | extrude 3
```

The _diameter_ is the cell's circumcircle and the cell faces front like a prism: `honeycomb 8 1.5` uses the footprint of `prism 6 8 3`.

| Tiling      | Cells                                                                 | Middle of the area's box        | Repeats at |
| ----------- | --------------------------------------------------------------------- | ------------------------------- | ---------- |
| `honeycomb` | hexagons in columns, each half a cell off its neighbours              | a cell's center                 | 60°        |
| `squares`   | squares in a plain grid, side `d / √2`                                | a cell's center                 | 90°        |
| `triangles` | triangles in rows, pointing back and front in turn, side `d * √3 / 2` | the corner where six cells meet | 60°        |
| `stripes`   | stripes of _width_ running left to right                              | a stripe's center               | 180°       |

A square of side 10 has diameter `(10 * 2 ** 0.5)`, as with a [`pyramid`](https://pegmatite.dev/guide/solids.md) of four sides. Every tiling is symmetric about both axes of its box.

### `angle`

`angle` turns the cells counter-clockwise seen from above, about the area's box center, the way [`rotate`](https://pegmatite.dev/guide/modifiers.md) turns a solid. The area stays where it is and the turned cells are cut back to it; `| rotate` would turn the whole result. `angle 90` runs stripes front to back.

```pegm
block 70 50 3
-squares 8 1.5 angle 45 rim 5 in rect 70 50 | extrude 3
```

## Shared rules

These hold for the four tilings and for `voronoi`.

- **Rim.** Cells stop short of the area's outline by a rim as wide as the strut unless `rim` sets it. A cell the rim crosses is cut back to it; stripes have their ends clipped. `rim 0` lets cells run out to the outline. A negative rim, or one so wide it leaves nothing of the area, is an error.
- **Area.** The area may be any shape: a face, a shape macro or another tiling. Its box is the tiling's slot even where cells do not reach its edges, and cells are arranged about that box's center.
- **Cell limit.** At most 10,000 cells, the most iterations a [pattern](https://pegmatite.dev/guide/patterns.md) runs. Each stripe counts as one cell.

```pegm
set $outline "M0,0 H80 L100,20 V40 H0 Z"
path $outline | extrude 3
-honeycomb 8 1.5 rim 3 in path $outline | extrude 3
```

## `voronoi`

**Syntax:** **`voronoi`** _strut_ [**`cells`** _count_] [**`seed`** _seed_] [**`points [`**_x_ _y_**`]`**…] [**`relax`** _passes_] [**`rim`** _width_] **`in`** _area_

Voronoi cells divide the area by proximity to sites. Give exactly one of `cells` or `points`, right after the strut; `seed` follows `cells` and is not allowed with `points`.

| Option   | Default                             | Rule                                                                                          |
| -------- | ----------------------------------- | --------------------------------------------------------------------------------------------- |
| `cells`  |                                     | scatters _count_ random sites inside the rim                                                  |
| `seed`   | `0`                                 | whole number. The same seed draws the same cells in every Pegmatite version                   |
| `points` |                                     | sites as `[x y]` in the area's frame, centered on its box                                     |
| `relax`  | `2` with `cells`, `0` with `points` | each pass moves every site to its cell's center, evening out sizes; over 50 warns and uses 50 |

```pegm
block 80 60 3
-voronoi 1.5 cells 30 seed 7 in rect 80 60 | extrude 3
```

```pegm
!@right 6
voronoi 1.2 cells 25 relax 0 in rect 60 60 | extrude 3
voronoi 1.2 cells 25 in rect 60 60 | extrude 3
voronoi 1.2 cells 25 relax 5 in rect 60 60 | extrude 3
```

```pegm
voronoi 1.5 points [-20 10] [15 12] [0 -10] [22 -12] [-18 -14] in rect 60 40 | extrude 3
```

A site outside the area still takes the part of the area nearest to it. A cell narrower than the strut vanishes, leaving its material.

### On faces

A tiling fits a face best when the face is its area. Each side of a vessel takes its own pattern and seed, and the rim keeps the corners standing. The label returns each cut to the vessel, which the next cut would not otherwise follow, and `on vase` is where each bare `#f` area is read from:

```pegm
vase: rect 40 40 | extrude 50 apex [0 0 -170] | shell 2
on vase #f2 -voronoi 1.5 cells 20 seed 1 in #f2 | extrude 2
on vase #f3 -voronoi 1.5 cells 20 seed 2 in #f3 | extrude 2
on vase #f4 -voronoi 1.5 cells 20 seed 3 in #f4 | extrude 2
on vase #f5 -voronoi 1.5 cells 20 seed 4 in #f5 | extrude 2
```