Annotate
Note
You will need to update file paths to reflect your own machine’s directory structure.
MapReader’s Annotate
subpackage is used to interactively annotate images (e.g. maps).
This is done in three simple steps:
Create an annotation tasks file
To set up your annotation tasks, you will need to create a separate annotation_tasks.yaml
file.
An example file which can be used as a template can be found in MapReader/worked_examples/
.
Your annotation_tasks.yaml
file needs to contain two sections: tasks
and paths
.
The tasks
section is used to specify annotation tasks and their labels.
This section can contain as many tasks/labels as you would like and should be formatted as follows:
tasks:
your_task_name:
labels: ["your_label_1", "your_label_2", "your_label_3"]
your_task_name_2:
labels: ["your_label_1", "your_label_2"]
Note
When annotating, for each patch you will only be able to select one label from your label list. So, if you envisage wanting to label something as “label_1” and also “label_2”, you will need to create a separate label combining “label_1 and label_2”.
The paths
section is used to specify file paths to sets of images you would like to annotate (annotation sets).
This section can contain as many annotation sets as you would like and should be formatted as follows:
paths:
your_annotation_set:
patch_paths: "./path/to/patches/"
parent_paths: "./path/to/parents/"
annot_dir: "./path/to/save/annotations"
your_annotation_set_2:
patch_paths: "./path/to/patches_2/"
parent_paths: "./path/to/parents_2/"
annot_dir: "./path/to/save/annotations_2"
For example, if you want to annotate ‘rail_space’ (as in this paper) and have been using the recommended/default directory structure, your annotation_tasks.yaml
should look like this:
#EXAMPLE
tasks:
rail_space:
labels: ["no_rail_space", "rail_space"]
paths:
set_001:
patch_paths: "./patches/patch-*png"
parent_paths: "./maps/*png"
annot_dir: "./annotations_one_inch"
Annotate your images
Note
Run these commands in a Jupyter notebook (or other IDE), ensuring you are in your mr_py38 python environment.
To prepare your annotations, you must specify a userID
, annotation_tasks_file
(i.e. the annotation_task.yaml
), tell MapReader which task
you’d like to run and which annotation_set
you would like to run on.
e.g. following our ‘rail_space’ example from earlier:
#EXAMPLE
from mapreader.annotate.utils import prepare_annotation
annotation = prepare_annotation(
userID="rosie",
annotation_tasks_file="annotation_tasks.yaml",
task="rail_space",
annotation_set="set_001",
)
You can then interactively annotate a sample of your images using:
annotation
To help with annotating, you can set the annotation interface to show a context image using context_image=True
.
This creates a second panel in the annotation interface, showing your patch in the context of a larger region whose size, in pixels, is set by xoffset
and yoffset
.
e.g. :
#EXAMPLE
annotation=prepare_annotation(
userID="rosie",
annotation_tasks_file="annotation_tasks.yaml",
task="rail_space",
annotation_set="set_001",
context_image=True,
xoffset=100,
yoffset=100)
annotation
By default, your patches will be shown to you in a random order but, to help with annotating, can be sorted by their mean pixel intensities using sortby="mean"
.
You can also specify min_mean_pixel
and max_mean_pixel
to limit the range of mean pixel intensities shown to you and min_std_pixel
and max_std_pixel
to limit the range of standard deviations within the mean pixel intensities shown to you.
This is particularly useful if your images (e.g. maps) have collars or margins that you would like to avoid.
e.g. :
annotation=prepare_annotation(
userID="rosie",
annotation_tasks_file="annotation_tasks.yaml",
task="rail_space",
annotation_set="set_001",
context_image=True,
xoffset=100,
yoffset=100,
min_mean_pixel=0.5,
max_mean_pixel=0.9
)
annotation
Save your annotations
Once you have annotated your images, you should save your annotations using:
#EXAMPLE
from mapreader.annotate.utils import save_annotation
save_annotation(
annotation,
userID="rosie",
task="rail_space",
annotation_tasks_file="annotation_tasks.yaml",
annotation_set="set_001",
)
This saves your annotations as a csv
file in the annot_dir
specified in your annotation tasks file.
For example, if you have downloaded your maps using the default settings of our Download
subpackage or have set up your directory as recommended in our Input Guidance, and then saved your patches using the default settings:
project
├──your_notebook.ipynb
└──maps
│ ├── map1.png
│ ├── map2.png
│ ├── map3.png
│ ├── ...
│ └── metadata.csv
└──patches
│ ├── patch-0-100-#map1.png#.png
│ ├── patch-100-200-#map1.png#.png
│ ├── patch-200-300-#map1.png#.png
│ └── ...
└──annotations_one_inch
└──rail_space_#rosie#.csv