FindBoundingBox

Find bounding boxes that satisfy the specified constraints.

Bounding boxes pixel data is optionally returned as blobs (encoded images) in the array of blobs.

Parameters

  • [optional] _ref: Reference to be used within the transaction.

  • [optional] unique: Indicates whether a single object is expected to satisfy the constraints.

  • [optional] image: Reference to an image within the transaction (either the result of a FindImage or an AddImage) from which the corresponding bounding boxes will be retrieved.

  • [optional] blobs: indicates whether the blobs will be returned as part of the response (Default: false).

  • [optional] coordinates: indicates whether the coordinates of the bounding box will be returned as part of the response (Default: false).

  • [optional] labels: indicates whether or not the label associated with the Bounding Box will be retrieved

  • [optional] uniqueids: indicates whether unique ids will be returned as part of the response (Default: false).

  • [optional] as_format: Specify the format of the returned bounding boxes [“jpg”, “png”]. By default, the boxes will keep the original format of the image.

  • [optional] in_rectangle

  • [optional] with_label

  • [optional] constraints

  • [optional] is_connected_to

  • [optional] group_by_source

  • [optional] operations

  • [optional] results

  • [optional] batch

Details

Either image OR is_connected_to can be present, not both. It is also possible to specify neither image nor is_connected_to, in which case the search will be constraint by the constraints.

By default, this command does not return the pixel data corresponding to the bounding box. One can specify that the pixel data be returned but setting the “blobs” parameter to “true”, in which case, the encoded pixel data of the bounding box will be returned as a blob.

If only one ref parameter is used in the is_connected_to array, the resulting objects obtained after traversing the given connection can be associated with their source objects by specifying the parameter group_by_source as true. The parameter is ignored if is_connected_to is absent. It is set to false by default.

in_rectangle

The in_rectangle parameter is used to specify the constraints on the positions of the bounding boxes:

"in_rectangle": {
    "x": 200,
    "y": 100,
    "w": 300,
    "h": 300
}

where x and y are the coordinates of the upper left corner of the BoundingBox and w and h are the width and height.

If in_rectangle is specified, the bounding boxes returned must be fully within the boundaries indicated by the given rectangle parameters.

Examples

Find the bounding boxes connected to the image with “unique_id” = 34, and of the label = “Dog”:

[ {
    "FindImage" : {
        "_ref" : 1,
        "constraints" : {
            "unique_id" : [ "==", 34]
        }
    }
},{
    "FindBoundingBox": {
        "image" :      1,
        "blobs":       false,       // Do not retrieve pixel data
        "coordinates": true,        // Retrieve coordinates
        "labels":      true,        // Retrieve label
        "with_label": "Dog"        // Filter by label
        "results": {
            "list": ["id"]
        }
    }
} ]

Find the bounding boxes connected to the image with “unique_id” = 34, and that are inside a given rectangle:

[ {
    "FindImage" : {
        "_ref" : 1,
        "constraints" : {
            "unique_id" : [ "==", 34]
        }
    }
},{
    "FindBoundingBox": {
        "image" :      1,
        "blobs":       false,       // Do not retrieve pixel data
        "coordinates": true,        // Retrieve coordinates
        "labels":      true,        // Retrieve label
        "in_rectangle": {
            "x":      100,
            "y":      100,
            "width":  500,
            "height": 500
        },
        "results": {
            "list": ["id"]
        }
    }
} ]

Find all bounding boxes with the “label” = “dog” and “year” = 2005, and retrieve each bounding box pixel data, encoded as “jpg”:

[ {
    "FindBoundingBox": {
        "with_label": "Dog",
        "constraints" : {
            "year" : ["==", 2005]
        },
        "blobs":  true,
        "format": "jpg"
    }
} ]