Skip to content

Home

Jump to bottom
Markus Fleischhacker edited this page May 6, 2020 · 10 revisions

Welcome to the BoundingBoxEditor wiki!

User Manual

Based on Bounding Box Editor Generic badge.

The following pages describe how to use the application's main functions. Functions are grouped by topic.

Images

Opening an image folder

To open an image folder, click File > Open Folder... and select the folder which contains the images you want to annotate. The following image formats are supported:

  • JPEG
  • PNG
  • BMP

Navigating the images

To navigate the loaded images, you can either use the navigation buttons on the top of the main image panel, use the shortcut keys A (previous image) and D (next image) or you can directly click on images in the Images side-panel.


Navigation buttons

Zooming and panning an image

Move your mouse-pointer over the central main image panel, hold Ctrl (Cmd on Mac) and use your mouse-wheel to zoom in and out of the image relative to the mouse-pointer position. To pan the zoomed image, hold Ctrl (Cmd on Mac), then click and drag the image to change the visible portion.


Zooming and panning

Resetting the image size and re-centering the image

To reset an image to its selected default size (see Setting default image size mode) and re-center it in the main image panel, click on the corresponding Reset Image Size and Center icon in the top panel of the main image panel.

Setting the default image size mode

By toggling the View > Maximize Images menu-item, you can choose between two different modes for the default size of loaded images in the main image panel. If Maximize Images is ticked, images will by default be displayed as large as the window size allows while still showing the whole image. If set to off, images will be displayed in a size that is as close as possible to the size it had when it was originally loaded.

Searching image files

You can search and select image files in the Search filename text-field at the top of the right side-panel. Filenames are searched as you type and the first file whose filename starts with the typed string will be selected automatically.


Searching image files

Categories

You can find the categories panel at the top of the left side-panel. It shows a list of currently existing object categories. The currently selected category is highlighted.


Categories panel

Adding and removing a category

To add a new object-category, type the name of the new category into the Category Name text-field (shortcut: Ctrl+N (Cmd+N on Mac) to focus), optionally choose a color for the category using the color-picker, then press Enter or click the Add button to create the new category. The newly created category will be selected automatically.

Note: Category names are case sensitive and must be unique.

To delete a category, click on the x icon next to the category name.

Note: You cannot delete a category that has bounding boxes assigned to it. Trying to do so will result in an error dialog being shown that displays the number of bounding boxes which are currently assigned to the category.

Editing a category

You can change the name of an existing category by clicking on the category's name and typing the new name and then pressing Enter (note that category names are case sensitive and must be unique). To change the color of a category right click on the category and use the color-picker on the Color menu item.

Searching a category

You can search categories by their name using the Search Category text-field at the top of the categories panel (shortcut: Ctrl+F (Cmd+F on Mac) to focus). Categories are searched as you type and the first category that starts with the typed sequence of letters will be selected automatically.

Bounding Boxes

A bounding box (rectangular or polygonal) can at any given time be in any of the following three states:

  1. Selected (opaque fill and move/resize handles visible): Select a bounding box by either directly clicking on it in the main image panel or by clicking on its corresponding item in the Annotated objects tree.
  2. Highlighted (opaque fill): Highlight a bounding box by either hovering directly over it in the main image panel or by hovering over its corresponding item in the Annotated objects tree.
  3. Neither selected nor highlighted (transparent fill)


The bounding box states 1 (selected), 2 (highlighted) and 3 (neither)

Hiding and unhiding a bounding box

To temporarily hide a bounding box, either right click the box itself or its corresponding item in the Annotated objects tree and then choose Hide in the context menu. You can also click on the rectangular icon on the box's tree-item to toggle its visibility on and off. Another way of hiding the currently selected box is by using the shortcut Ctrl+H (Cmd+H on Mac) and unhiding it with Ctrl+V (Cmd+V on Mac). To hide and unhide all bounding boxes at once, use the eye off/on icons on the left side of the main image panel toolbar or use the shortcuts Ctrl+Alt+H (Cmd+Alt+H on Mac) and Ctrl+Alt+V (Cmd+Alt+V on Mac).

Note: Hiding is recursive, if you hide a bounding box, all bounding boxes belonging to its child categories will also be hidden.

Hiding and unhiding a category

You can click on the rectangular icon on a category's tree-item to toggle the visibility of all assigned bounding boxes on and off. Alternatively right click the category's tree-item and click Hide in the context-menu.


Hiding and unhiding bounding boxes

Deleting a bounding box

To delete a bounding box, either right click the box itself or its corresponding item in the Annotated objects tree and then choose Delete in the context menu. Alternatively you can use press the Delete-key to delete the currently selected bounding box.

Note: Deleting is recursive, if you delete a bounding box, all bounding boxes belonging to its child categories will also be deleted.

Nesting bounding boxes

The program allows you to nest bounding boxes using the Annotated objects tree. In the example below the bounding box corresponding to the object Nose 1 is made a part of the bounding box corresponding to the object Face 1 by dragging and dropping its tree item on top of Face 1 object's tree item.


Nesting and 'unnesting' a bounding box

Nesting categories

You can also make a whole category (including all its child bounding boxes) a child of a target bounding box by dragging and dropping it on target's corresponding tree item.


Nesting and 'unnesting' a whole category.

Changing the category of an existing bounding box

You can change the assigned category of an existing bounding box by right-clicking on the box itself or on its corresponding item in the Annotated objects tree and clicking on the Change Category context-menu entry. A small window pops that lets you choose the new category out of the currently existing categories in the Categories panel.


Changing the category of an existing bounding box.

Adding and removing tags to and from a bounding box

You can tag existing bounding boxes by using the Tags panel. To add a new tag to a bounding box, first select it (see Selected state) then click on New tag in the Tags panel (shortcut Ctrl+T (Cmd+T on Mac) to focus and type the tag-name. Finally press Enter to add the new tag to the tag-list of the selected bounding box. Currently, only the following tag-names will be considered when saving or loading annotations to/from files:

  • difficult
  • occluded
  • truncated
  • pose: ...
  • action: ...

For bounding boxes with at least one tag, a small tag icon will be displayed next to their corresponding tree-item in the Annotated objects tree.

Note: Tag-names are case-sensitive and must be unique (Nothing happens if you try to add a tag with an already existing tag-name).

To remove a tag from the tag-list of a bounding box, select the box then click on the x-icon next to the tag you want to delete in the Tags panel.


Adding and removing tags to and from a bounding box

Shape specific functions - Rectangular Bounding Boxes

Drawing a new rectangular bounding box

To create a new rectangular bounding box, you first have to select the category it should be assigned to in the Categories panel, and make sure that you are in Rectangle Drawing-Mode (CTRL-K).


Rectangle Drawing Mode selected

Then draw the bounding box on the image in the main image panel by clicking, dragging and then releasing the primary mouse button. The newly created bounding box will be automatically selected and a corresponding entry in the Annotated objects tree will be created.


Drawing a rectangular bounding box

Note: Annotated images can be recognized in the Images side-panel by a bold-face image title and a highlighted left border.

Resizing and moving a rectangular bounding box

To be able to resize a bounding box, it has to be selected first, then you can drag the resize handles to change the size. To move a bounding box, click inside it, then drag your mouse.


Moving and resizing a bounding box

Shape specific functions - Polygonal Bounding Boxes

Drawing a new polygonal bounding box

To create a new polygonal bounding box, you first have to select the category it should be assigned to in the Categories panel, and make sure that you are in Polygon Drawing-Mode (CTRL-P).


Polygon Drawing Mode selected

Then create a new polygonal bounding box by subsequently clicking on the image with the primary mouse button to create connected vertices. Notice that the first and currently last vertex are highlighted to indicate that a new vertex will be created between them. Once you are finished, right click anywhere on the image to finalize the polygon. A corresponding entry in the Annotated objects tree will be created automatically.


Drawing a polygonal bounding box

Note: Polygonal bounding boxes cannot be moved as a whole.

Modifying an existing polygonal box

After a polygonal box was created you can still modify its shape and add or delete vertices. You may move existing vertices by clicking and dragging them using the primary mouse button. To add new vertices you must first select a path of vertices by middle-clicking on consecutive vertices of the polygon. Then either SHIFT + Middle-Click inside the polygon or right click on the polygon and then click the Add Vertices entry in the context menu. This will add one new vertex between each pair of selected vertices. To delete selected vertices, either press SHIFT-DELETE or use the Delete Vertices context menu entry.


Modifying a polygonal bounding box

Annotations

Exporting annotations

To save all image annotations in your current session click File > Export Annotations. You can then choose between saving the annotations using the Pascal-VOC format... or the YOLO format... menu entries. Finally the program will ask you to specify the target folder for the annotation files.

Saving annotations in Pascal VOC format

If you choose Pascal-VOC format, the annotations will be saved as XML files. For every image that contains at least one bounding box (rectangular or polygonal), exactly one XML file will be created. The filename of annotation files follows the pattern:

<image-filename>_<image-file-extension>_A.xml

For example, the annotation file for an image file dummy.png would be named dummy_png_A.xml.
Sample annotation


Sample annotation

An annotation file containing the following data was produced after annotating a single image with 3 bounding boxes as in the image above and then clicking the File > Save Annotations... menu-item:

<annotation>
    <folder>Samples</folder>
    <filename>alexander-popov-Xbh_OGLRfUM-unsplash.jpg</filename>
    <size>
        <width>3000</width>
        <height>2000</height>
        <depth>3</depth>
    </size>
    <object>
        <name>Car</name>
        <difficult>0</difficult> 
        <occluded>0</occluded>
        <pose>Back</pose>
        <truncated>0</truncated>
        <actions>
            <driving>1</driving>
        </actions>
        <bndbox>
            <xmin>1000.22</xmin>
            <xmax>1258.07</xmax>
            <ymin>1272.39</ymin>
            <ymax>1487.27</ymax>
        </bndbox>
        <part>
            <name>Taillight</name>
            <difficult>0</difficult>
            <occluded>0</occluded>
            <pose>Unspecified</pose>
            <truncated>0</truncated>
            <bndbox>
                <xmin>1009.07</xmin>
                <xmax>1046.98</xmax>
                <ymin>1336.85</ymin>
                <ymax>1363.4</ymax>
            </bndbox>
        </part>
        <part>
            <name>Taillight</name>
            <difficult>0</difficult>
            <occluded>0</occluded>
            <pose>Unspecified</pose>
            <truncated>0</truncated>
            <bndbox>
                <xmin>1155.69</xmin>
                <xmax>1203.3</xmax>
                <ymin>1338.54</ymin>
                <ymax>1360.45</ymax>
            </bndbox>
        </part>
    </object>
</annotation>

Note: The actions element will only be added if the corresponding bounding box contains at least one action tag. The elements difficult, truncated, occluded and pose however will always be added and their values set to defaults ('0' for the first three, 'Unspecified' for the latter) if the corresponding tag was not assigned to the bounding box.

Saving annotations in YOLO format

Important: Only rectangular bounding boxes are exported when using YOLO format because (to my knowledge) the YOLO object detection system cannot handle general polygonal boxes. Also, object tags are not supported by the YOLO format and will simply be ignored during the export.

If you choose to export using YOLO format, the annotations will be saved to one .txt-file per image which will be given the same name as the corresponding image file. Each of these files contains descriptions for the rectangular bounding boxes (one per line) belonging to the image:

<object-class> <x> <y> <width> <height>

Here x, y, width and height are given relative to the images width and height (i. e. the values are between 0 and 1). object-class is an index into a list of category names which are written to a file called object.data.

Importing annotations

You can import existing image annotations from a folder containing annotation files in either the Pascal-VOC format or the YOLO format, by clicking File > Import Annotations > Pascal-VOC format.../YOLO format... and selecting the import-directory. If errors occur during the import-process, a dialog window will be displayed, showing you the files which could not be imported as well as a description of the errors. Some of the errors that could occur while loading an annotation from a file include:

  • The annotation file could not be opened.
  • The file contains data of an annotation to an image file which is not currently loaded in the application.
  • The annotation file does not conform to the expected format (e.g.: non-optional elements missing).

Pascal-VOC format specifics

When importing annotations from existing files, the following XML-elements are optional (No tags will be produced as a result of these lines):

<difficult>0</difficult>
<occluded>0</occluded>
<pose>Unspecified</pose>
<truncated>0</truncated>
<actions></actions>

All other elements occurring in the sample annotation XML-output are mandatory. Importing an XML-file with any missing mandatory elements will result in an error.

Note: Some annotation files, such as those contained in the Pascal VOC 2012 dataset, may contain additional XML-elements e.g.: source, database, image, segmented ... - currently these elements are ignored.

Clone this wiki locally