Annotator Guide¶
This guide explains step by step, how to annotate images using the built-in
annotation app. We will use an example image from Lenna for this tutorial.
The annotator app is agnostic to images and can load anything that is supported
by bob.io.image.
Image annotation¶
The application is launched via command-line, which means you need a command prompt, pre-configured with the conda environment containing this package. Open such prompt (e.g. via a Terminal application) and pass the root path containing the image you would like to annotate:
$ conda activate myenv
(myenv) $ bob annotate -vv /path/to/images /path/to/annotations
The output path, marked on the above example with /path/to/annotations is
the directory where annotated points will be written to. This path is created
if it does not exist. If it does exist, annotations are preloaded for each
image inside /path/to/images if they exist and annotation is resumed from
the point it was stopped.
The app will scan for image files with a given extension name (.png by
default) on the input path provided (e.g.: /path/to/images). Images will
then be sorted and displayed in alphabetical order, one after the other so you
can annotate or review their annotation. Annotations are saved to the output
directory copying the same folder structure found on the input path. For
example, if the images were lying like this on the input path:
/path/to/images/subfolder1/image.png
/path/to/images/subfolder2/image.png
/path/to/images/subfolder3/subfolder/image.png
Then, the output path will contain the following files, after the user annotated all images:
/path/to/annotations/subfolder1/image.json
/path/to/annotations/subfolder2/image.json
/path/to/annotations/subfolder3/subfolder/image.json
Annotation format¶
Annotations are saved in JSON format, which is easily readable and loadable in a variety of programming environments. The specific format used by the annotator application may change, but it essentially just lists annotated points, in the order objects are created.
Zoom¶
You may alternatively control the size of the image being annotated by passing
a zoom parameter (floating point number within the range ]0,+inf[). A
zoom of 1.0 (the default), displays images as they are. A zoom larger than
1.0 upscales the input image making it look bigger than they originally
are. A zoom factor smaller than 1.0 does the inverse, scaling down the
input image. Annotations recorded on the image are independent of the zoom
factor and compensated upon saving operations. To change the zoom factor, use
the --zoom parameter of the annotator app, while starting the application.
For example, to start the application with a zoom factor of 2.0 do:
(myenv) $ bob annotate -vv --zoom=2.0 /path/to/images /path/to/annotations
Tip
You should try to use a zoom factor which is the largest possible given your screen resolution. The image should fit comfortably on the screen without resizing the drawing window. The higher the zoom factor, the more precise will be your annotation. Conversely, the lower, the less precise.
The application supports automatic resizing of the canvas to fill all the available application area, without distorting the image or the annotations. Use this feature to select the largest possible annotation area (typically by fully maximizing the annotation window), which will give you the best possible precision.
Further help¶
Use the flag --help to list all options and examples from the annotation
app:
(myenv) $ bob annotate --help
Read the annotator application help message, which lists all known keyboard and
pointer/mouse bindings. Familiarise yourself with these shortcuts as that
improves annotation performance, reducing the time you spend annotating images.
You can check the contents of the help dialog through this documentation,
looking at the docstring of the bob.ip.annotator.gui module.