# How do I draw annotations?

```{admonition} What will I learn?
- How to draw annotations
- How to select, measure and delete annotations
- How to assign classes to annotations
- How to show, hide and fill annotations
- How to change other annotation properties
```

Analysis in QuPath involves representing the contents of the image in terms of **objects**.

An object could be big (e.g. an entire piece of tissue) or small (e.g. an individual cell).
QuPath has different kinds of objects to handle this variation.

The first objects we'll look at are **annotations**.
The easiest way to create an annotation is to draw it yourself.

```{note}
An *object* in QuPath is like a *region of interest (ROI)* in ImageJ, but with some extra features.
Objects are described in more detail [in the QuPath docs](https://qupath.readthedocs.io/en/stable/docs/concepts/objects.html).
```


## Drawing annotations

QuPath provides different tools to draw annotations.
They are all found towards the left of the toolbar.
You can hover over any toolbar button to see an explanation of what it does, as well as any shortcut key.

Here's an image of an ancient church annotated using different tools.

```{figure} ../../images/annotating/named-annotation-zoo.png
A view of Anglesey annotated with QuPath
``` 

Drawing annotations is easier when you use the right tool -- so it's worth taking time to explore them all.

```{admonition} What to do
1. Open `CMU-1.svs`
2. Follow the instructions below to explore all the annotation tools.
```

### {{ icon_rectangle }} Rectangle tool

```{admonition} What to do
1. Select the **Rectangle** tool {{ icon_rectangle }}
    - Or type {kbd}`R`
2. Click on a starting point and drag to the opposite corner to draw a rectangle.
3. Lift the mouse button to complete the rectangle.
```

Note that QuPath will automatically switch to activate the **Move** tool {{ icon_move }} after the rectangle is done.
This is convenient for two main reasons:
1. It stops you accidentally drawing more rectangles until you remember to turn off the tool.
2. It allows you to *move* the rectangle itself.

```{admonition} What to do
5. Make sure the **Move** tool is selected
6. Click inside the rectangle annotation and drag to *move* it to another location
7. Click at the corner of the rectangle to *move* the corner to another location (i.e. resize the rectangle)
```

```{figure} ../../images/annotating/rectangle.gif
Rectangle tool without and with holding {kbd}`Shift`
```

```{admonition} Question
The **Move** tool {{ icon_move }} can be used to *move* an annotation, or to *move* part of an annotation (e.g. the corner of a rectangle, to resize it).

What is the other purpose of the **Move** tool {{ icon_move }} we've seen already?
```

<!-- 1. Moving around the image (panning)
2. Moving an annotation
3. Moving the corner of a rectangle (resizing) -->


### {{ icon_ellipse }} Ellipse tool

```{admonition} What to do
1. Select the **Ellipse** tool {{ icon_ellipse }}
    - Or type the letter {kbd}`O`
2. Click on a starting point and drag to a different location.
3. Lift the mouse button to complete the ellipse.
```

```{figure} ../../images/annotating/ellipse.gif
Ellipse tool without and with holding {kbd}`Shift`
```

### {{ icon_line }} Line tool

```{admonition} What to do
1. Select the **Line** tool {{ icon_line }}
    - Or type {kbd}`L`
2. Click on a starting point and drag to a different location.
3. Lift the mouse button to complete the line.
```

Drawing rectangles, ellipses and lines in QuPath use exactly the same process -- just with a different tool.

```{tip}
If you hold {kbd}`Shift` while drawing a rectangle or ellipse, the shape is constrained to be a square or a circle.
If you hold {kbd}`Shift` while drawing a line, the angle is constrained to be a multiple of 45°.
```

```{figure} ../../images/annotating/line.gif
Line tool without and with holding {kbd}`Shift`
```

### {{ icon_polygon }} Polygon tool

```{admonition} What to do
1. Select the **Polygon** tool {{icon_polygon}}
    - Or type {kbd}`P`
2. Click on the image to add one point
3. Click on more locations to add more points
4. Double-click to add the final point and complete the polygon
```

Sometimes, you might want a polygon with *lots* of points, and you don't want to add them individually.
There is a different way to create a polygon, using exactly the same tool.

```{admonition} What to do
5. Select the **Polygon** tool {{icon_polygon}}
    - Or type {kbd}`P`
6. Press *and hold* the left mouse button down on the image
7. Drag the cursor to draw 'freehand'
8. *Release* the mouse button complete the polygon
```

The mode of drawing depends upon what you do from the start: click once, or click and drag.

```{figure} ../../images/annotating/polygon.gif
Polygon tool
```

### {{ icon_polyline }} Polyline tool

```{admonition} What to do
1. Select the **Polyline** tool {{icon_polygon}}
    - Or type {kbd}`V`
2. Click on the image to add one point
3. Click on more locations to add more points
4. Double-click to add the final point and complete the polyline
```

As with the polygon tool, you can also use the click-and-drag approach to create a polyline.

```{admonition} Polygon or polyline?
The polyline and polygon tools behave almost identically.
The difference is:
* the **polygon** tool defines an **area**: the first and last points are automatically connected.
* the **polyline** tool defines a **line**: the first and last points are *not* connected.

This can cause confusion if you draw a polyline and intentionally put the last point close to the first point.
The annotation might *look* like a polygon... but it isn't.
The measurements you get for each will be different.
```

```{figure} ../../images/annotating/polyline.gif
Polyline tool
```

### {{ icon_brush }} Brush tool 

```{admonition} What to do
1. Select the **Brush** tool {{icon_brush}}
    - Or type {kbd}`B`
2. Click and drag the mouse over the image to paint with the brush
3. Lift the mouse to complete your annotation
4. Zoom in or out in the viewer, and repeat the process to paint new annotations
```

The **Brush** tool behaves a bit differently from the tools we've met so far.
1. The size of the annotation depends upon how zoomed in you are in the viewer.
   - Zoom in to draw detailed annotations, zoom out to draw big ones.
2. Once you lift your mouse, QuPath *doesn't* automatically return to the **Move** tool.
   - You'll need to press the **Move** tool button {{icon_move}} or type {kbd}`M`.

The reason QuPath doesn't switch back to **Move** automatically is that the brush is really powerful for quickly creating and editing annotations.
Often, you'll want to keep it selected.

```{admonition} What to do
5. With the **Brush** tool still selected
   - Click inside an existing area annotation (i.e., not a line or polyline) and drag beyond the annotation to edit it
   - Repeat the process, but while pressing {kbd}`Alt/Option`. This turns the brush into an eraser to subtract areas from an existing annotation.
```

There's one other advanced brush trick, which is useful when you want to create annotations that are beside one another but shouldn't overlap.

```{admonition} What to do
6. With the **Brush** tool still selected
   - Start drawing a new annotation *outside* an existing area annotation
   - Draw *into* the existing annotation so that they overlap
   - While still holding the mouse button down, press {kbd}`Ctrl/Cmd+Shift` to tell QuPath to remove the overlap
```

```{figure} ../../images/annotating/brush.gif
Brush tool
```

### {{ icon_wand }} Wand tool

```{admonition} What to do
1. Select the **Wand** tool {{icon_wand}}
    - Or type {kbd}`W`
2. Click and drag the mouse over the image to paint with the wand
3. Lift the mouse to complete your annotation
```

The **Wand** tool acts like the **Brush** tool, with one important difference: it pays attention to the colours in the image.
This is great if you want to quickly annotate areas that have a high contrast with the background.
If not, the brush is probably better because it gives you more control.

Like the brush, the wand pays attention to zoom level.
The same shortcut keys also work to convert the wand to become an eraser or prevent overlaps.

```{figure} ../../images/annotating/wand1.gif
Wand tool being used for detailed areas
```

```{figure} ../../images/annotating/wand2.gif
Wand tool being used for large areas
```

### {{ icon_points }} Points tool 

The **Points** tool is a special case, typically used for counting.
It's also a *little* more awkward to use (at least until we've covered more topics), so we won't spend time on it here.

See the [Manual Counting](https://qupath.readthedocs.io/en/stable/docs/starting/cell_counting.html) section of the docs for details.

## Selecting, measuring & deleting annotations

### Selecting one annotation (from a list)

```{admonition} What to do
1. Open the {guilabel}`Annotations` tab on the left.
2. Click on an annotation in the list to select it.
3. View the measurements in the table below.
4. Edit the annotation in the viewer by moving it, resizing it, or adding/erasing parts.
5. Watch the measurements update.
```

QuPath automatically makes measurements of annotations.
When an annotation is selected, you can see these in the table under the {guilabel}`Annotations` tab.

```{admonition} Question
Does QuPath provide the same measurements for every annotation, or does it depend upon the tool you used to draw it?
```

<!-- It depends on the tool - you get different measurements for lines and areas -->

### Selecting multiple annotations (in the viewer)

```{admonition} What to do
1. Make sure the **Move** tool {{ icon_move }} is selected.
2. Double-click inside an annotation on the viewer to select it.
3. *Single* click on more annotations with the {kbd}`Alt` key pressed (or {kbd}`Option` key on a Mac).
```

Annotations can also be selected by (double) clicking on them in the viewer, with the **Move** tool active.
If you hold down the {kbd}`Ctrl` or {kbd}`Cmd` key, you can click to select multiple annotations.

### Deleting annotations

```{admonition} What to do
1. Select an annotation you don't like the look of.
2. Press {kbd}`Backspace` to delete it -- or choose {guilabel}`Delete` under the {guilabel}`Annotations` tab.
```

The quickest way to delete individual annotations is to select them and then press {kbd}`Backspace`.

```{admonition} Question
How could you quickly delete **all** the annotations you've drawn?

_Hint: There are different ways to do this -- a good way to find at least one of them is with the help of {kbd}`Ctrl/Cmd+L`._
```


## Locking & unlocking annotations

The **Move** tool {{ icon_move }} and brush or wand can sometimes make it _too_ easy to edit an annotation.

To help avoid accidental edits, annotations can be locked.
You can still delete a locked annotation, but it's harder to make accidental changes from the viewer.

```{admonition} What to do
1. Select an annotation you *do* like the look of.
2. Right-click on the annotation (either in the viewer, or under the {guilabel}`Annotations` tab)
3. Look for an option to {guilabel}`Lock` the annotation, and select this.
4. Try to move the annotation in the viewer _(this should not work!)_.
5. Try to delete the annotation _(this should work!)_.
```

Sometimes, QuPath will *automatically* lock annotations for you -- for example, if you've used the annotation to define a region for cell detection.
This means you often won't need to explicitly choose to lock your annotations.
Still, it's important to know that locking is possible -- and if you can't edit an annotation as you want, you might need to _unlock_ it.


## Assigning classes to annotations

A feature of QuPath objects is that they can be assigned **classes** (sometimes called **classifications**).
Classes help identify objects that share specific characteristics.

```{admonition} What to do
1. Select an annotation.
2. Under the {guilabel}`Annotations` tab, look for the {guilabel}`Class list`
3. Select a class from the list
4. Press the {guilabel}`Set selected` button to assign the class to the annotation
5. Right-click on the viewer and look for *another* way to assign the class to the annotation
6. Right-click on the viewer *while holding down the {kbd}`Shift` key* to find a *third* way to assign the class to the annotation
```

Assigning classes is such a crucial step in using QuPath that there are multiple ways to do it.
But the key thing you'll need to get started is to know where to find the {guilabel}`Class list` under the {guilabel}`Annotations` tab.

### Creating your own classes

```{admonition} What to do
1. Click on the {guilabel}`+` beside {guilabel}`Class list` under the {guilabel}`Annotations` tab
2. Create a new class with the name **Artifacts**
```

There are some extra buttons around the {guilabel}`Class list` that show how it can be edited and used, for example pressing {guilabel}`+` or {guilabel}`-` to add and remove classes respectively.

```{figure} ../../images/annotating/2-adding_class.jpg
Creating a custom class
```

## Setting other annotation properties

```{admonition} What to do
1. Find an area of folded tissue in `CMU-1.svs`
2. Use an annotation tool (or tools!) to draw over the folded area.
3. With the annotation selected, press {kbd}`Enter`.
4. Set the class of the annotation to **Artifacts** and the name to **Folded tissue**. You can change the colour and add a description at the same time if you want.
```

To modify the properties of an annotation, you can select it in the viewer and press the {kbd}`Enter` key.
Alternatively, or you can right-click on the annotation under the {guilabel}`Annotations` tab and choose {menuselection}`Set properties`.

If you set the annotation's **name**, this can be seen in the viewer.


```{figure} ../../images/annotating/3-after_properties.jpg
Setting the annotation properties
```

```{figure} ../../images/annotating/4-after_properties2.jpg
Examples of added properties
```

```{admonition} Class or name?

You'd set the class of an annotation when it's relevant for analysis and it expresses a property that other objects might have (e.g., you might assign the class `Tumor` to lots of cells, and the `Stroma` class to others).

Names are used less often -- usually to identify a *specific* object.
For example, names can be useful to add a label different areas (e.g. `Region 1`, `Region 2`) to help you distinguish between them after exporting your analysis results.
```


## Showing, hiding & filling annotations

```{admonition} What to do
1. Create some annotations
2. Click anywhere in the viewer
3. Press the {kbd}`A` key several times, to show and hide the annotations
4. Press {kbd}`Shift+F` several times, to fill and unfill the annotations
```

If you have a lot of objects in QuPath, you won't necessarily want to see all of them all of the time.
Some of QuPath's toolbar buttons and shortcut keys help you adjust how things are displayed.

This table shows the main ones.
The first 3 are relevant to annotations, the last 2 are for a different type of object we'll meet soon: **detections**.

|Icon |Shortcut    | Description                                       |
|------------|------------|---------------------------------------------------|
|{{icon_annotations}} | {kbd}`A`         | Show/hide annotation objects                     |
|{{ icon_annotations_fill }} | {kbd}`Shift+F`         | Fill/unfill annotation objects              |
|{{ icon_show_names }} | {kbd}`N`         | Show/hide annotation names (when available)              |
|{{ icon_detections }} | {kbd}`D`         | Show/hide detection objects                 |
|{{ icon_detections_fill }} | {kbd}`F`    | Fill/unfill detection objects                 |


```{admonition} Question
Which shortcut from the table would be useful to help distinguish between a **polygon** and a **polyline**?
```

<!-- Shift+F -->


## Putting it all together

```{admonition} Challenge
1. Add the image `hugo.jpg` to your project.
   - Set type to {guilabel}`Other`.  
2. Use the annotation tools to annotate Hugo's head.
3. Create a new class **Good boy** by clicking on the {guilabel}`+` beside {guilabel}`Class list`.
4. Select the head annotation and change its properties by pressing {kbd}`Enter` or right-clicking on the annotation and clicking {menuselection}`Set properties`.
   - Add it to the class **Good boy**.
   - You could also name it **Hugo**.
5. How big is Hugo's head in terms of area and perimeter?  
   - What are the units of measurement?  
   - Where are these defined?
```

```{seealso}
* [First steps](https://qupath.readthedocs.io/en/stable/docs/starting/first_steps.html)
* [Annotating images](https://qupath.readthedocs.io/en/stable/docs/starting/annotating.html)
* [Manual counting](https://qupath.readthedocs.io/en/stable/docs/starting/cell_counting.html) 
* [Objects](https://qupath.readthedocs.io/en/stable/docs/concepts/objects.html)
```