A bounding box in essence, is a rectangle that surrounds an object, that specifies its position, class(eg: car, person) and confidence(how likely it is to be at that location). Bounding boxes are used on object detection tasks where it is necessary to localize and classify an object in the data.

Import

Python SDK

Rectangle is a type of ObjectAnnotation

Definition

Rectangle(start = Point_top_left, end = Point_bottom_right)

Parameter

Value

start

(Point): Top left coordinate of the bounding box

end

(Point): Bottom right coordinate of the bounding box

Supported data types

Data type

Supported

Image, Geospatial, Documents

Yes

Video

Coming soon

bbox_xyxy = [10,10,60,110]

ObjectAnnotation(
  name = "bbox_xyxy",
  value = Rectangle(start = Point(x = bbox_xyxy[0], y = bbox_xyxy[1]), end = Point(x = bbox_xyxy[2], y = bbox_xyxy[3])),
)
## Coordinates in the desired EPSG coordinate system
bbox_top_left = Point(x=-99.21052827588443, y=19.405662413477728)
bbox_bottom_right = Point(x=-99.20534818927473, y=19.400498983095076)

ObjectAnnotation(
  name = "bbox_geospatial",
  value = Rectangle(start = bbox_top_left, end = bbox_bottom_right),
)

Format convertors

Method

Usage

Comments

from_xyhw()

Rectangle.from_xyhw(bbox_xyhw)

Transforms a bounding box from x,y,h,w format to x1,y1,x2,y2 format.

from_shapely()

Rectangle.from_shapely(shapely_object)

Transforms a shapely object.

If the provided shape is a non-rectangular polygon, a rectangle will be
returned based on the min and max x,y values.

bbox_xyhw = [10,10,50,100]

ObjectAnnotation(
            value = Rectangle.from_xyhw(*bbox_xyhw),
            name = class_name
)
from shapely.geometry import Polygon
poly = Polygon([(2, 2), (4, 4), (4, 8), (8, 8), (8, 4)])

## Converts shapely polygon object to a bounding box
ObjectAnnotation(
  name = "from_shapely",
  value = Rectangle.from_shapely(poly),
)

NDJSON

NDJSON format is recommended if an annotation type is not yet supported in Python SDK or if you are unable to use the Python environment.

Definition

Parameter

Asset type

Required

Description

uuid

Image, Tiled imagery, Video

Yes

A user-generated UUID for each annotation. If you import an annotation to a Data Row and there is already an imported annotation with the same uuid on that Data Row, the latest import will override the previous one. The uuid must be 128 bits (32 characters). The following formats are supported:

  • A0EEBC99-9C0B-4EF8-BB6D-6BB9BD380A11
  • {a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11}
  • a0eebc999c0b4ef8bb6d6bb9bd380a11
  • a0ee-bc99-9c0b-4ef8-bb6d-6bb9-bd38-0a11
  • {a0eebc99-9c0b4ef8-bb6d6bb9-bd380a11}

schemaId

Image, Tiled imagery, Video

Yes

The ID of the schema that contains all of the information needed for rendering your annotation.

dataRow.id

Image, Tiled imagery, Video

Yes

The ID of the Data Row where you want to attach the imported annotations.

bbox.top

Image, Tiled imagery, Video

Yes

y-coordinate of bounding box top-left corner.

bbox.left

Image, Tiled imagery, Video

Yes

x-coordinate of bounding box top-left corner.

bbox.height

Image, Tiled imagery, Video

Yes

Height of bounding box in pixels.

bbox.width

Image, Tiled imagery, Video

Yes

Width of bounding box in pixels.

segments

Video

Yes

Segments are continuous portions of the instances track in the video.

Whenever an object enters or leaves a new segment is created

segments.[keyframes]

Video

Yes

A segment is defined by its keyframes. Labelbox interpolates the geometry of the bounding box between key frames.

As a best practice it is good to use as few key frames as possible to reduce the challenge for labelers

Supported data types

Data type

Supported

Image, Video, Geospatial, Document

Format

{
    "uuid": "efca0c21-5206-4da6-8cb5-d6ca43649cfa",
    "schemaId": "ck67grts29n7x0890atmeiahw",
    "dataRow": {
         "id": "cjxav4aa07r1g0dsq70t9eveg"
     },
     "bbox": {
         "top": 153,
         "left": 34,
         "height": 204,
         "width": 67
     }
}
{
    "uuid": "efca0c21-5206-4da6-8cb5-d6ca43649cfa",
    "schemaId": "ck67grts29n7x0890atmeiahw",
    "dataRow": {
         "id": "cjxav4aa07r1g0dsq70t9eveg"
     },
     "bbox": {
         "top": 153,
         "left": 34,
         "height": 204,
         "width": 67
     }
}
{
  "uuid": uuid,
  "schemaId": schema_id,
  "dataRow": {
    "id": datarow_id
  },
  "segments": [
    {
      "keyframes": [
        {
          "frame": 5,
          "bbox": {
            "top": 80,
            "left": 80,
            "height": 80,
            "width": 80
          }
        },
        {
          "frame": 12,
          "bbox": {
            "top": 100,
            "left": 100,
            "height": 200,
            "width": 100
          }
        },
        {
          "frame": 20,
          "bbox": {
            "top": 125,
            "left": 125,
            "height": 200,
            "width": 300
          }
        }
      ]
    },
    {
      "keyframes": [
        {
          "frame": 22,
          "bbox": {
            "top": 50,
            "left": 50,
            "height": 50,
            "width": 50
          }
        },
        {
          "frame": 25,
          "bbox": {
            "top": 75,
            "left": 75,
            "height": 75,
            "width": 100
          }
        }
      ]
    },
    {
      "keyframes": [
        {
          "frame": 27,
          "bbox": {
            "top": 80,
            "left": 50,
            "height": 80,
            "width": 50
          }
        }
      ]
    }
  ]
}

Export

When you export your bounding Box annotations from Labelbox, the export file will contain the following information for each bounding box.

Python SDK

The export format of the bounding box is similar to the import format.

Learn more about exporting annotations using the SDK here

JSON

You will receive a JSON file when you generate an export from the app.

Parameter

Asset type

Description

schemaId

Image, Video, Tiled imagery, Document

The ID of the schema containing all of the information needed for rendering your annotation.

featureId

Image, Video, Tiled imagery, Document

ID of the annotation.

title

Image, Video, Tiled imagery, Document

Name of the annotation in the ontology.

color

Image, Video, Tiled imagery, Document

Color of the annotation in the ontology.

bbox.top

Image, Video, Document

y-coordinate of bounding box top-left corner.

bbox.left

Image, Video, Document

x-coordinate of bounding box top-left corner.

bbox.height

Image, Video, Document

Height of bounding box in pixels.

bbox.width

Image, Video, Document

Width of bounding box in pixels.

instanceURI

Image, Document

Annotation information hosted on Labelbox servers.

keyframe

Video

When keyframe is true, it means that a labeler created or made an adjustment to the annotation on that frame. When keyframe is false, it means the annotation was auto-populated or interpolated on that frame.

page

Document

The page number of that the bounding box is for

unit

Document

Will be "POINTS" for PDF documents. Points represent 1/72 of an inch.

type

Tiled imagery

Annotation type. Value should by rectangle.

geometry.coordinates

Tiled imagery

Longitude and latitude, in that order.

Format

{
    "featureId": "ck9bmeej61emf0yf5bgjb4tjw",
    "schemaId": "ck9blmq1lnlxw08895jy7zsk4",
    "title": "Blue bird",
    "value": "blue_bird",
    "color": "#FF8000",
    "bbox": {
        "top": 186,
        "left": 192,
        "height": 300,
        "width": 519
    }
}
{
    "featureId": "ck9bmeej61emf0yf5bgjb4tjw",
    "schemaId": "ck9blmq1lnlxw08895jy7zsk4",
    "title": "Car 1",
    "value": "car_1",
    "color": "#1CE6FF",
    "keyframe": false,
    "bbox": {
        "top": 1164,
        "left": 2538,
        "height": 222,
        "width": 119
    }
}
{
    "featureId": "ckossvopo00013h68phgicget",
    "schemaId": "ckosstz24fhch0yag6h6k6vem",
    "title": "bbox",
    "value": "bbox",
    "color": "#1CE6FF",
    "type": "rectangle",
    "geometry": {
        "coordinates": [
            [
                [
                    151.20171129670584,
                    -33.86658193385505
                ],
                [
                    151.20171129670584,
                    -33.86615404807865
                ],
                [
                    151.20256960353075,
                    -33.86615404807865
                ],
                [
                    151.20256960353075,
                    -33.86658193385505
                ],
                [
                    151.20171129670584,
                    -33.86658193385505
                ]
            ]
        ]
    }
}
{
    "featureId": "cky8ybaew00013g67ywqyfboe",
    "schemaId": "cky8xqathotfg10axdntqcja1",
    "title": "Sample object 1",
    "value": "sample_object_1",
    "color": "#70d4e0",
    "bbox": {
        "top":107.442,
        "left":102.326,
        "height":181.116,
        "width":274.232
    }
    "page":1,
    "unit":"POINTS", // points represent 1/72 of an inch.