Tools to work with the Oriented Bounding Box Schema.
This package provides a class OBBAnns
which allows annotations in the OBB schema to be loaded, visualized, and metrics against proposals to be calculated.
Below, an example of a visualization of the DeepScoresV2 dataset, which uses the OBB schema, can be seen.
-
Install SWIG. This can be installed executing the following line on linux
sudo apt install swig
or by downloading the windows executable at swig.org
On Mac, SWIG can be install with Homebrew via
brew install swig
.If installing using the windows executable, then the path to the SWIG executable must be added to the
Path
variable. -
Install the obb_anns module. This can be done with the following command.
git clone https://github.com/yvan674/obb_anns python3 setup.py develop # Installs it in place
The OBBAnns toolkit assumes the following directory structure
dataset/
├── images/
│ ├── img1.png
│ ├── img2.png
│ └── ...
├── segmentation/
│ ├── img1_seg.png
│ ├── img2_seg.png
│ └── ...
└── annotations.json
The file top level directory and the annotations file can have any name, but the annotations file must be within the top level directory.
{
"info": {
"description": (str) description,
"version": (str) version number,
"year": (int) year released,
"contributor": (str) contributor,
"date_created": (str) "YYYY/MM/DD",
"url": (Optional str) URL where dataset can be found
},
"annotation_sets": (list[str]) ["deepscores", "muscima", ...]
"categories": {
"cat_id": {
"name": (str) category_name,
"annotation_set": (str) "deepscores",
"color": (int or tuple[int]) color value of cat in segmentation file
},
...
},
"images": [
{
"id": (str) n,
"file_name": (str) "file_name.jpg",
"width": (int) x,
"height": (int) y,
"ann_ids": (list[str]) ann_ids
},
...
],
"annotations": {
"ann_id": {
"a_bbox": (list of floats) [x0, y0, x1, y1],
"o_bbox": (list of floats) [x0, y0, x1, y1, x2, y2, x3, y3],
"cat_id": (list[str]) cat_id,
"area": (float) area in pixels,
"img_id": (str) img_id,
"comments": (str) any additional comments about the annotation.
},
...
}
}
Notes:
- The annotation file is in JSON format.
- The top level field
annotation_sets
is meant to be used when a dataset can be used with different class names. For example, if we have two datasetsdataset_a
anddataset_b
and there is a viable mapping between the two datasets,annotation_sets
will have the value [dataset_a
,dataset_b
]. By adding this field and specifying which class belongs to which annotation_set under categories, this allows one dataset to be compatible with both annotation category names, useful for benchmarking. - The field
a_bbox
ando_bbox
of annotations is the aligned and oriented bounding boxes for each annotation, respectively. - The bounding boxes are given as absolute values.
a_bbox
contains the coordinates of the top left and bottom right corners.o_bbox
contains the coordinates of each of the corners of the oriented bounding box.cat_id
,ann_id
, andimg_id
are stringified ints and start at 1.cat_id
is a list of stringified ints. It is a list as there are multiple annotation sets. For example, supposed we have two annotation setsdataset_a
anddataset_b
. If the category 'stem' has a cat_id of '1' indataset_a
and a cat_id of 25 indataset_b
, then thecat_id
field of a single stem annotation would be['1', '25']
. I a category doesn't exist in one of the annotation sets, a value ofnull
should be provided.
- Segmentations are found in a png file named '[filename]_seg.png' in the directory "segmentation".
- The segmentation file is a grayscale 8-bit png image where the pixel values correspond to the cat_id.
- If more categories are required, alternative mappings can be defined by overriding the _parse_ann_info method.
Proposals are what the network should generate so that this package is able to process the proposals to calculate precision, accuracy, and recall.
{
"annotation_set": (str) annotation set used,
"proposals": [
{
"bbox": list[float] [x1, y1,..., x4, y4], or list[float] [x0, y0, x1, y1]
"cat_id": (str) cat_id,
"img_id": (int) img_id
},
...
]
}
Notes:
- The proposals file is in JSON format.
bbox
is in the same format as for annotations- If
bbox
has a length of 8, it is treated as an oriented bounding box. If it has length 4, then it is treated as an aligned bbox. - A check is done to make sure all img_idxs and cat_ids that are referred to in the proposal file is in the annotation file to make sure that the proposals corresponds to the correct annotations file.
The OBBAnns class provides all the necessary tools to work with the OBB schema.
Usage is simply to initialize the class by providing it with the annotation file path, then loading the annotations into memory.
from obb_anns import OBBAnns
o = OBB