How do I draw annotations?

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.

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.

Fig. 23 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.

What to do

1. Open CMU-1.svs

2. Follow the instructions below to explore all the annotation tools.

Rectangle tool

What to do

1. Select the Rectangle tool

   • Or type 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 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.

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)

Fig. 24 Rectangle tool without and with holding Shift

Question

The Move tool 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 we’ve seen already?

Ellipse tool

What to do

1. Select the Ellipse tool

   • Or type the letter O

2. Click on a starting point and drag to a different location.

3. Lift the mouse button to complete the ellipse.

Fig. 25 Ellipse tool without and with holding Shift

Line tool

What to do

1. Select the Line tool

   • Or type 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 Shift while drawing a rectangle or ellipse, the shape is constrained to be a square or a circle. If you hold Shift while drawing a line, the angle is constrained to be a multiple of 45°.

Fig. 26 Line tool without and with holding Shift

Polygon tool

What to do

1. Select the Polygon tool

   • Or type 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.

What to do

5. Select the Polygon tool

   • Or type 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.

Fig. 27 Polygon tool

Polyline tool

What to do

1. Select the Polyline tool

   • Or type 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.

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.

Fig. 28 Polyline tool

Brush tool

What to do

1. Select the Brush tool

   • Or type 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 or type 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.

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 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.

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 Ctrl/Cmd+Shift to tell QuPath to remove the overlap

Fig. 29 Brush tool

Wand tool

What to do

1. Select the Wand tool

   • Or type 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.

Fig. 30 Wand tool being used for detailed areas

Fig. 31 Wand tool being used for large areas

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 section of the docs for details.

Selecting, measuring & deleting annotations

Selecting one annotation (from a list)

What to do

1. Open the 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 Annotations tab.

Question

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

Selecting multiple annotations (in the viewer)

What to do

1. Make sure the Move tool is selected.

2. Double-click inside an annotation on the viewer to select it.

3. Single click on more annotations with the Alt key pressed (or 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 Ctrl or Cmd key, you can click to select multiple annotations.

Deleting annotations

What to do

1. Select an annotation you don’t like the look of.

2. Press Backspace to delete it – or choose Delete under the Annotations tab.

The quickest way to delete individual annotations is to select them and then press Backspace.

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 Ctrl/Cmd+L.

Locking & unlocking annotations

The Move tool 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.

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 Annotations tab)

3. Look for an option to 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.

What to do

1. Select an annotation.

2. Under the Annotations tab, look for the Class list

3. Select a class from the list

4. Press the 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 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 Class list under the Annotations tab.

Creating your own classes

What to do

1. Click on the + beside Class list under the Annotations tab

2. Create a new class with the name Artifacts

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

Fig. 32 Creating a custom class

Setting other annotation properties

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 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 Enter key. Alternatively, or you can right-click on the annotation under the Annotations tab and choose Set properties.

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

Fig. 33 Setting the annotation properties

Fig. 34 Examples of added properties

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

What to do

1. Create some annotations

2. Click anywhere in the viewer

3. Press the A key several times, to show and hide the annotations

4. Press 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
	A	Show/hide annotation objects
	Shift+F	Fill/unfill annotation objects
	N	Show/hide annotation names (when available)
	D	Show/hide detection objects
	F	Fill/unfill detection objects

Question

Which shortcut from the table would be useful to help distinguish between a polygon and a polyline?

Putting it all together

Challenge

1. Add the image hugo.jpg to your project.

   • Set type to Other.

2. Use the annotation tools to annotate Hugo’s head.

3. Create a new class Good boy by clicking on the + beside Class list.

4. Select the head annotation and change its properties by pressing Enter or right-clicking on the annotation and clicking 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?

See also

• First steps

• Annotating images

• Manual counting

• Objects