Box2D is a type of label with a 2D bounding box on an image. It’s usually used for object detection task.

Each data can be assigned with multiple Box2D labels.

The structure of one Box2D label is like:

    "box2d": {
        "xmin": <float>
        "ymin": <float>
        "xmax": <float>
        "ymax": <float>
    "category": <str>
    "attributes": {
        <key>: <value>
    "instance": <str>

To create a LabeledBox2D label:

>>> from tensorbay.label import LabeledBox2D
>>> box2d_label = LabeledBox2D(
... xmin, ymin, xmax, ymax,
... category="<LABEL_CATEGORY>",
... instance="<LABEL_INSTANCE_ID>"
... )
>>> box2d_label
LabeledBox2D(xmin, ymin, xmax, ymax)(
  (category): '<LABEL_CATEGORY>',
  (attributes): {...}
  (instance): '<LABEL_INSTANCE_ID>'


LabeledBox2D extends Box2D.

To construct a LabeledBox2D instance with only the geometry information, use the coordinates of the top-left and bottom-right vertexes of the 2D bounding box, or the coordinate of the top-left vertex, the height and the width of the bounding box.

>>> LabeledBox2D(10, 20, 30, 40)
LabeledBox2D(10, 20, 30, 40)()
>>> LabeledBox2D.from_xywh(x=10, y=20, width=20, height=20)
LabeledBox2D(10, 20, 30, 40)()

It contains the basic geometry information of the 2D bounding box.

>>> box2d_label.xmin
>>> box2d_label.ymin
>>> box2d_label.xmax
>>> box2d_label.ymax
Vector2D(30, 40)
Vector2D(10, 20)
>>> box2d_label.area()


The category of the object inside the 2D bounding box. See category for details.


Attributes are the additional information about this object, which are stored in key-value pairs. See attributes for details.


Instance is the unique ID for the object inside of the 2D bounding box, which is mostly used for tracking tasks. See instance for details.


Before adding the Box2D labels to data, Box2DSubcatalog should be defined.

Box2DSubcatalog has categories, attributes and tracking information, see common category information, attributes information and tracking information for details.

The catalog with only Box2D subcatalog is typically stored in a json file as follows:

    "BOX2D": {                                        <object>*
        "description":                                <string>! -- Subcatalog description, (default: "").
        "isTracking":                                <boolean>! -- Whether this type of label in the dataset contains tracking
                                                                   information, (default: false).
        "categoryDelimiter":                          <string>  -- The delimiter in category names indicating subcategories.
                                                                   Recommended delimiter is ".". There is no "categoryDelimiter"
                                                                   field by default which means the category is of one level.
        "categories": [                                <array>  -- Category list, which contains all category information.
                "name":                               <string>* -- Category name.
                "description":                        <string>! -- Category description, (default: "").
        "attributes": [                                <array>  -- Attribute list, which contains all attribute information.
                "name":                               <string>* -- Attribute name.
                "enum": [...],                         <array>  -- All possible options for the attribute.
                "type":                      <string or array>  -- Type of the attribute including "boolean", "integer",
                                                                   "number", "string", "array" and "null". And it is not
                                                                   required when "enum" is provided.
                "minimum":                            <number>  -- Minimum value of the attribute when type is "number".
                "maximum":                            <number>  -- Maximum value of the attribute when type is "number".
                "items": {                            <object>  -- Used only if the attribute type is "array".
                    "enum": [...],                     <array>  -- All possible options for elements in the attribute array.
                    "type":                  <string or array>  -- Type of elements in the attribute array.
                    "minimum":                        <number>  -- Minimum value of elements in the attribute array when type is
                    "maximum":                        <number>  -- Maximum value of elements in the attribute array when type is
                "parentCategories": [...],             <array>  -- Indicates the category to which the attribute belongs. Do not
                                                                   add this field if it is a global attribute.
                "description":                        <string>! -- Attribute description, (default: "").


* indicates that the field is required. ! indicates that the field has a default value.

To add a LabeledBox2D label to one data:

>>> from tensorbay.dataset import Data
>>> data = Data("<DATA_LOCAL_PATH>")
>>> data.label.box2d = []
>>> data.label.box2d.append(box2d_label)


One data may contain multiple Box2D labels, so the Data.label.box2d must be a list.