Skip to main content

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] with_label
  • [optional] image_ref: 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] in_rectangle
  • [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] areas: indicates whether to return the areas enclosed by the bounding boxes, in pixels (default: false).
  • [optional] labels: indicates whether or not the label associated with the Bounding Box will be retrieved
  • [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.

Details​

Either image_ref OR is_connected_to can be present, not both. It is also possible to specify neither image_ref nor is_connected_to, in which case the search will be constrained 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. Similarly, if the image_ref parameter is used, the results can be grouped by the source image. The parameter is ignored if neither is_connected_to nor image_ref is used. It is set to false by default.

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]
            },
            "blobs": true
        }
    }, {
        "FindBoundingBox": {
            "image_ref": 1,
            "blobs": false,
            "coordinates": true,
            "labels": true,
            "with_label": "Dog",
            "results": {
                "list": ["label_id"]
            }
        }
    }]

Successful response:


    [{
        "FindImage": {
            "blobs_start": 0,
            "returned": 1,
            "status": 0
        }
    }, {
        "FindBoundingBox": {
            "entities": [{
                "_coordinates": {
                    "height": 40,
                    "width": 40,
                    "x": 120,
                    "y": 50
                },
                "_label": "Dog",
                "label_id": 32
            }],
            "returned": 1,
            "status": 0
        }
    }]

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]
            },
            "blobs": true
        }
    }, {
        "FindBoundingBox": {
            "image_ref": 1,
            "blobs": false,
            "coordinates": true,
            "labels": true,
            "in_rectangle": {
                "x": 100,
                "y": 0,
                "width": 500,
                "height": 500
            },
            "results": {
                "list": ["id"]
            }
        }
    }]

Successful response:


    [{
        "FindImage": {
            "blobs_start": 0,
            "returned": 1,
            "status": 0
        }
    }, {
        "FindBoundingBox": {
            "entities": [{
                "_coordinates": {
                    "height": 40,
                    "width": 40,
                    "x": 120,
                    "y": 50
                },
                "_label": "Dog",
                "id": null
            }],
            "returned": 1,
            "status": 0
        }
    }]

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,
            "as_format": "jpg"
        }
    }]

Successful response:


    [{
        "FindBoundingBox": {
            "blobs_start": 0,
            "returned": 1,
            "status": 0
        }
    }]