# Geometry Primitives

Source: https://www.potatoannotator.com/docs/vision-spatial/geometry-primitives

**Potato's image surface covers bounding boxes, polygons, polylines, ellipses, 2D cuboids, keypoint sets with skeleton topology, and instance-keyed brush masks.** All of them are configured through `image_annotation`'s `tools` list.

```yaml
annotation_schemes:
  - annotation_type: image_annotation
    name: objects
    description: "Outline everything you find."
    source_field: image
    tools: [bbox, polygon, polyline, ellipse, cuboid_2d, keypoint_set, brush, eraser, sam]
    labels:
      - {name: vehicle, color: "#FF6B6B", key_value: "1"}
      - {name: person, color: "#4ECDC4", key_value: "2"}
```

Runnable example: [`examples/image/geometry-primitives/`](https://github.com/davidjurgens/potato/tree/main/examples/image/geometry-primitives).

## The tools

| Tool | Shape | Typical use |
|---|---|---|
| `bbox` | Rectangle | [Object detection](https://en.wikipedia.org/wiki/Object_detection) |
| `polygon` | Closed multi-point shape | [Instance segmentation](https://en.wikipedia.org/wiki/Image_segmentation) |
| `polyline` | Open path | Lane markings, cracks, cables |
| `ellipse` | Ellipse | Cells, apertures, round objects |
| `cuboid_2d` | Projected 3D box | Vehicles seen from a single camera |
| `keypoint_set` | Named points plus skeleton edges | Pose, faces, anatomical landmarks |
| `brush` / `eraser` | Painted mask | Fine-grained segmentation |
| `fill` | Colour-aware flood fill | Large uniform regions |
| `sam` | Click to segment | See [interactive segmentation](/docs/vision-spatial/segmentation) |

Keypoint sets carry [COCO](https://cocodataset.org/) visibility flags and a skeleton topology, so a pose exports as a pose rather than as a bag of points.

## Keyboard conventions changed in 2.8

Defaults now follow V7 and CVAT conventions:

| Key | Tool |
|---|---|
| `v` | Select |
| `r` | Rectangle |
| `b` | Brush |
| `f` | Fill |
| `k` | Keypoint |
| `[` / `]` | Decrease / increase size |

This is a change: `b` used to be bbox and `f` used to be freeform. A study already in the field can keep the old bindings:

```yaml
    keybinding_profile: legacy
```

Annotators see a one-time notice about the change rather than discovering it by drawing the wrong shape.

## Working faster

- **Per-class show and hide** with `h` and `Shift+H`, persisted across the whole project rather than reset per image.
- **Copy annotations from the previous image** with `Ctrl/Cmd+D`, or set `carry_over` to do it automatically. Useful for near-duplicate frames.
- **Two-finger pan and pinch zoom** for tablets and stylus work.

## Fixes worth stating

Several image features had shipped in earlier versions without working, and saying so is more useful than quiet correction:

- Accepting an AI detection called a method that did not exist, so it was a silent no-op.
- The freeform tool drew paths that were never saved.
- Brush strokes leaked between instances, through three separate instance-switch bugs.
- Image annotation was completely inert during the training phase.

All are fixed in 2.8. If you ran an image study on an earlier version, the training phase in particular is worth checking.

## Related

- [Interactive segmentation](/docs/vision-spatial/segmentation)
- [Text prompting](/docs/vision-spatial/text-prompting)
- [Geometry agreement](/docs/measurement/geometry-agreement)
- [Image annotation reference](/docs/annotation-types/image-annotation)