Repository navigation
Annotations
To save all image annotations in your current session click File > Export Annotations and choose one of the formats. File > Export as <format>... (Ctrl+S, Cmd+S on Mac) exports again in the most recently used format:
| Format | Menu entry | Saved to | Shapes |
|---|---|---|---|
| Pascal VOC | Pascal-VOC format... |
a folder, one XML file per annotated image | boxes and polygons, with nesting and tags |
| YOLO | YOLO format... |
a folder, one text file per annotated image, plus object.data
|
boxes and polygons (nested shapes as separate entries) |
| JSON | JSON format... |
a single file | boxes, polygons and masks, with nesting, tags and category colors |
| CSV | CSV format... |
a single file | boxes only (nested boxes as separate rows) |
| COCO | COCO format... |
a single file | boxes, polygons and masks (nested shapes as separate entries) |
| PNG masks | PNG masks... |
a folder with two mask images per annotated image | masks and polygons (filled) |
For the folder-based formats the program asks for the target folder, for JSON, CSV and COCO for the target file. If errors occur while saving, a report lists the affected files.
Masks can only be saved in the JSON, COCO and PNG mask formats. The other formats leave them out (together with shapes nested in them), and the report after saving says how many were not saved.
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
dummy.png would be named dummy_png_A.xml.
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 exporting it with File > Export Annotations > Pascal-VOC format...:
<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.
Polygonal bounding boxes are saved with a polygon element instead of bndbox, which lists the vertices' absolute image coordinates in order:
<polygon>
<x>1736.42</x>
<y>818.8</y>
<x>1732.89</x>
<y>949.39</y>
...
</polygon>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 (without its extension). Each line describes one bounding box:
- a rectangular box as
<object-class> <x-center> <y-center> <width> <height> - a polygonal box in YOLO's segmentation format as
<object-class> <x1> <y1> <x2> <y2> ...
All coordinates are given relative to the image's width and height (i.e. the values are between 0 and 1). object-class is an index into the list of category names, which is written to a file called object.data (one name per line). Nested bounding boxes are saved as separate lines, and tags are not supported by the format.
For example:
0 0.497002 0.519272 0.084716 0.513919
2 0.474129 0.164347 0.035581 0.245182
3 0.75 0.5 0.8 0.6 0.82 0.4
Note
Because the annotation files are named after the image files without their extension, images such as a.jpg and a.png would get the same annotation file. Such images are reported as errors instead of overwriting each other's annotations.
If you choose to export to JSON format, all annotations will be saved to a single .json file of your choosing. It contains one entry per annotated image with the image's details and its objects. Coordinates are relative to the image's width and height; nested objects are listed in parts:
[
{
"image": {
"fileName": "austin-neill-685084-unsplash.jpg",
"details": { "folderName": "1", "width": 3854.0, "height": 2033.0, "depth": 3 }
},
"objects": [
{
"polygon": [0.45055, 0.402755, 0.449634, 0.46699, ...],
"category": { "name": "Boat", "color": "#C31D8F" },
"tags": [],
"parts": [
{
"bndbox": { "minX": 0.471064, "minY": 0.773281, "maxX": 0.521103, "maxY": 0.816291 },
"category": { "name": "Boat", "color": "#C31D8F" },
"tags": ["pose: right"],
"parts": []
}
]
}
]
}
]Masks are saved with a mask element instead of bndbox or polygon. It holds the mask as a compressed run-length encoding, as in the COCO format (size is [height, width] of the image in pixels):
{
"mask": { "size": [2033, 3854], "counts": "Xk`n15ma13M3N2M2O..." },
"category": { "name": "Boat", "color": "#C31D8F" },
"tags": [],
"parts": []
}If you choose to export to CSV format, the rectangular bounding boxes of all images are saved to a single .csv file (the format used by e.g. the TensorFlow Object Detection API). Each row describes one box, with absolute pixel coordinates:
filename,width,height,class,xmin,ymin,xmax,ymax
"nico-bhlr-1067059-unsplash.jpg",6000,4000,Surfboard,2976,1006,3750,3674
"nico-bhlr-1067059-unsplash.jpg",6000,4000,Surfboard,2098,907,2791,3741Nested boxes are saved as separate rows. Polygonal boxes and tags are not supported by the format and are skipped.
The COCO format is the common format for instance segmentation (used e.g. by Detectron2, MMDetection and torchvision). All annotations are saved to a single .json file with the lists images, categories and annotations:
- boxes are saved as
bbox([x, y, width, height]in pixels); - polygons as a polygon
segmentation([[x1, y1, x2, y2, ...]]); - masks as a compressed run-length
segmentation({"size": [height, width], "counts": "..."}), as written by pycocotools.
Nested shapes are saved as separate annotations, and tags are not saved. Each category also gets a color field (not part of COCO; other tools ignore it), so that the colors are kept when the file is imported again.
PNG masks follow the layout of Pascal VOC's segmentation data. The chosen folder receives
-
SegmentationObject/<image name>.png: for each pixel, the number of the object it belongs to (1, 2, ...); -
SegmentationClass/<image name>.png: for each pixel, the number of the object's category; -
classes.txt: the category names, one per line (line 1 is category 1).
0 is the background. The images use Pascal VOC's color palette, so they can be viewed as they are. Masks are saved as they are and polygons are filled; boxes are left out (the report after saving says how many). Where objects overlap, a pixel belongs to the one saved later, e.g. a nested object. An image can contain at most 254 objects and 254 categories.
You can import existing image annotations with File > Import Annotations and one of the formats above. Pascal VOC, YOLO and PNG mask annotations are imported from a folder, JSON, CSV and COCO annotations from a single file. Imported annotations are added to the existing ones, and categories that don't exist yet are created.
If errors occur during the import-process, a dialog window will be displayed, showing you the files (or entries) which could not be imported as well as a description of the errors. Some of the errors that could occur while loading an annotation 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).
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. Each object (and part) needs either a bndbox or a polygon element, but not both.
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.
The import folder must contain the object.data file with the category names. An annotation file is assigned to the loaded image with the same name (ignoring the extension); if there is no such image, or more than one, the file is reported as an error. Lines with 4 coordinates are imported as rectangular boxes, lines with 6 or more coordinates as polygons. Coordinates that are outside the image by less than 0.000001 (e.g. due to rounding by other tools) are accepted and moved to the image border.
The file must contain the header row shown above. Rows referring to images that are not currently loaded are reported as errors. New categories are created with random colors.
An annotation without a segmentation is imported as a box, one with a single polygon as a polygon, and one with several polygons (an object in several parts) as a mask. Run-length masks are read both compressed and uncompressed (as used for iscrowd annotations); their size must match the image's size in the file's images list. Images are matched by file name. Invalid images, categories and annotations are reported, and the rest is imported.
The import folder must contain classes.txt and the SegmentationClass folder. Each object number in an object mask becomes a mask, with the category that most of its pixels have in the category mask. Without a SegmentationObject folder, each category in a category mask becomes one mask. Mask files are assigned to the loaded image with the same name (ignoring the extension). The masks must be indexed or grayscale PNGs; pixels with the value 255 (Pascal VOC's "void" border) are ignored.
Annotations that you haven't exported yet are saved automatically a few seconds after each change, so that they aren't lost if the program crashes or the computer shuts down unexpectedly. There is one file per image folder, in the app's JSON format, in the application data folder:
| System | Folder |
|---|---|
| Windows | %APPDATA%\BoundingBoxEditor\autosave |
| macOS | ~/Library/Application Support/BoundingBoxEditor/autosave |
| Linux |
$XDG_DATA_HOME/boundingboxeditor/autosave (usually ~/.local/share/boundingboxeditor/autosave) |
The automatic save doesn't replace exporting: it is deleted as soon as you export the annotations, and when you quit and choose not to save them.
When you open a folder that has an automatic save, the program asks whether to restore it (Restore Unsaved Annotations). Restored annotations still count as not exported. If the most recently opened folder has one when the program starts, it offers to open that folder and restore them.
The circle on the left of the status bar is red while there are annotations that aren't exported yet, and green once everything is exported. Its tooltip says when the annotations were last saved automatically.