# Drawing (pyzed.draw)

> API reference for pyzed.draw: shapes, paths, text and transforms for drawing custom 2D graphics on a pz.canvas in Python desktop apps.

Source: https://albakore.github.io/pyzed/reference/draw/

<!-- Generated by docs/scripts/gen_api.py. Edit docs/scripts/api_docs_en.py. -->

`pyzed.draw` shapes are plain dicts you pass to [`pz.canvas`](https://albakore.github.io/pyzed/reference/widgets/#canvas).
Angles are in degrees and `y` grows downwards. See the [drawing with canvas](https://albakore.github.io/pyzed/guides/canvas/) guide.

```python
from pyzed import draw

pz.canvas([
    draw.background("#1e2127"),
    draw.circle(100, 100, 40, fill="#74ade8"),
    draw.text(100, 180, "Hello", color="#dce0e5", align_x="center"),
], width=200, height=200)
```

## Shapes

### `background`

```python
background(color)
```

Fills the whole canvas.

| Parameter | Description |
| --- | --- |
| `color` | Color. |

### `rect`

```python
rect(x, y, w, h, *, fill=None, stroke=None, width=1.0, radius=0.0, dash=None)
```

A rectangle, filled and/or stroked.

| Parameter | Description |
| --- | --- |
| `x` | Left. |
| `y` | Top. |
| `w` | Width. |
| `h` | Height. |
| `fill` | Fill color. |
| `stroke` | Stroke color. |
| `width` | Stroke width. |
| `radius` | Corner radius. |
| `dash` | Dash pattern, e.g. `[6, 4]`. |

### `rects`

```python
rects(items, *, fill)
```

Many rectangles filled with one color in a single shape (fast for grids and bars).

| Parameter | Description |
| --- | --- |
| `items` | `(x, y, w, h)` tuples. |
| `fill` | Color. |

### `circle`

```python
circle(x, y, r, *, fill=None, stroke=None, width=1.0, dash=None)
```

A circle centered at `(x, y)`.

| Parameter | Description |
| --- | --- |
| `x` | Center x. |
| `y` | Center y. |
| `r` | Radius. |
| `fill` | Fill color. |
| `stroke` | Stroke color. |
| `width` | Stroke width. |
| `dash` | Dash pattern, e.g. `[6, 4]`. |

### `line`

```python
line(x1, y1, x2, y2, *, stroke='#ffffff', width=1.0, dash=None, cap=None)
```

A straight line.

| Parameter | Description |
| --- | --- |
| `x1` | Start x. |
| `y1` | Start y. |
| `x2` | End x. |
| `y2` | End y. |
| `stroke` | Stroke color. |
| `width` | Stroke width. |
| `dash` | Dash pattern, e.g. `[6, 4]`. |
| `cap` | `"round"`, `"square"` or `"butt"`: shape of the line ends. |

### `polyline`

```python
polyline(
    points,
    *,
    stroke='#ffffff',
    width=1.0,
    closed=False,
    fill=None,
    dash=None,
    cap='round',
)
```

Joins `points` with straight lines (`closed=True` closes the shape).

| Parameter | Description |
| --- | --- |
| `points` | List of `(x, y)`. |
| `stroke` | Stroke color. |
| `width` | Stroke width. |
| `closed` | Closes the shape. |
| `fill` | Fill color. |
| `dash` | Dash pattern, e.g. `[6, 4]`. |
| `cap` | `"round"`, `"square"` or `"butt"`: shape of the line ends. |

### `polygon`

```python
polygon(points, *, fill=None, stroke=None, width=1.0)
```

A closed shape through `points`.

| Parameter | Description |
| --- | --- |
| `points` | List of `(x, y)`. |
| `fill` | Fill color. |
| `stroke` | Stroke color. |
| `width` | Stroke width. |

### `arc`

```python
arc(x, y, r, start, end, *, stroke=None, fill=None, width=1.0, pie=False, cap=None)
```

A circular arc from `start` to `end` degrees (0 = 3 o'clock, clockwise). `pie=True` closes it through the center (pie slice).

| Parameter | Description |
| --- | --- |
| `x` | Center x. |
| `y` | Center y. |
| `r` | Radius. |
| `start` | Start angle. |
| `end` | End angle. |
| `stroke` | Stroke color. |
| `fill` | Fill color. |
| `width` | Stroke width. |
| `pie` | Closes through the center. |
| `cap` | `"round"`, `"square"` or `"butt"`: shape of the line ends. |

### `path`

```python
path(ops, *, fill=None, stroke=None, width=1.0, dash=None, cap=None)
```

A free-form path with SVG-like operations: `("M", x, y)` move, `("L", x, y)` line, `("Q", cx, cy, x, y)` quadratic curve, `("C", c1x, c1y, c2x, c2y, x, y)` cubic curve, `("A", cx, cy, r, start, end)` arc, `("Z",)` close.

| Parameter | Description |
| --- | --- |
| `ops` | List of operations. |
| `fill` | Fill color. |
| `stroke` | Stroke color. |
| `width` | Stroke width. |
| `dash` | Dash pattern, e.g. `[6, 4]`. |
| `cap` | `"round"`, `"square"` or `"butt"`: shape of the line ends. |

### `text`

```python
text(
    x,
    y,
    content,
    *,
    color='#ffffff',
    size=14,
    font='sans',
    weight=None,
    align_x='start',
    align_y='top',
)
```

Text anchored at `(x, y)`; `align_x`/`align_y` choose which side of the text sits on that point.

| Parameter | Description |
| --- | --- |
| `x` | X position. |
| `y` | Y position. |
| `content` | The text. |
| `color` | Color. |
| `size` | Size. |
| `font` | Family. |
| `weight` | Weight. |
| `align_x` | `"start"`, `"center"` or `"end"`. |
| `align_y` | `"top"`, `"center"` or `"bottom"`. |

### `image`

```python
image(source, x, y, w, h, *, rotation=0.0, opacity=1.0, pixelated=False, size=None)
```

A bitmap (sprite) drawn in the box `(x, y, w, h)`. Decoded once per source and cached, so drawing it every frame is cheap. See [Making games](https://albakore.github.io/pyzed/games/).

| Parameter | Description |
| --- | --- |
| `source` | A path, encoded image bytes (PNG, JPEG…) or raw RGBA bytes with `size`. |
| `x` | Left. |
| `y` | Top. |
| `w` | Width. |
| `h` | Height. |
| `rotation` | Degrees, around its center. |
| `opacity` | From 0 to 1. |
| `pixelated` | Nearest-neighbor scaling, for pixel art. |
| `size` | `(width, height)` of raw RGBA bytes. |

## Transforms

### `translate`

```python
translate(x, y)
```

Offsets the shapes that come after it.

| Parameter | Description |
| --- | --- |
| `x` | Horizontal. |
| `y` | Vertical. |

### `rotate`

```python
rotate(degrees)
```

Rotates the shapes that come after it around the current origin.

| Parameter | Description |
| --- | --- |
| `degrees` | Degrees. |

### `scale`

```python
scale(x, y=None)
```

Scales the shapes that come after it.

| Parameter | Description |
| --- | --- |
| `x` | Horizontal factor. |
| `y` | Vertical factor (defaults to `x`). |

### `save`

```python
save()
```

Saves the current transform (use it with `restore`).

### `restore`

```python
restore()
```

Goes back to the transform saved by the last `save`.

### `group`

```python
group(shapes, *, x=0.0, y=0.0, rotation=0.0, scale_by=None)
```

Draws `shapes` translated, rotated and scaled without affecting the following shapes. Returns a list: expand it with `*`.

| Parameter | Description |
| --- | --- |
| `shapes` | The shapes. |
| `x` | X offset. |
| `y` | Y offset. |
| `rotation` | Degrees. |
| `scale_by` | Scale. |