.. _FindBoundingBox: FindBoundingBox =============== Find bounding boxes that satisfy the specified constraints. Bounding boxes pixel data is optionally returned as blobs (encoded images) in the :ref:`array of blobs `. Requires an authenticated user with ``objects.read`` permission. Parameters ---------- .. include:: find_parameters.rst .. list-table:: :header-rows: 1 :widths: 22 23 55 * - Parameter - Type / required - Default and behavior * - :ref:`with_label ` - string / optional - Omitted: no label filter. Compare the stored _label for exact equality. * - :ref:`image_ref ` - integer 1–100000 / optional - Omitted: no parent-image restriction. Must refer to images declared earlier in this query; intersect their bounding boxes with other filters, including is_connected_to. * - :ref:`in_rectangle ` - object / optional - Omitted: no spatial restriction. Require the box to lie fully inside x, y, width, height. All four fields are integers; x/y are 0–2147483647 and width/height are 1–2147483647. * - :ref:`blobs ` - boolean / optional - false; true returns an encoded crop from each bounding box's associated image. Requires retrievable parent image data; no input blob is consumed. * - ``as_format`` - string: jpg, png, tif / optional - Omitted: preserve the parent image encoding. Re-encode returned crops only when blobs:true; stored images are unchanged. * - ``coordinates`` - boolean / optional - false; true returns the rectangle as _coordinates with x, y, width, height. * - ``areas`` - boolean / optional - false unless results.all_properties:true; true returns stored _area in square pixels. Explicit false disables this extra property selection. * - ``labels`` - boolean / optional - false unless results.all_properties:true; true returns _label. Explicit false disables this extra property selection. Details ------- **image_ref** and **is_connected_to** can be combined; both restrictions apply. Omit either to remove that restriction. Property and rectangle filters are intersected with the selected image relationships. 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. .. include:: group_by_source_details_image_ref.rst Response and recovery --------------------- A successful command returns ``status: 0`` and ``returned``. Requested metadata appears in ``entities``; a reference-only lookup can match objects without returning metadata. ``returned`` counts delivered objects or blobs, not every graph match. Use ``results.count`` to request a match count. When blobs are returned, ``blobs_start`` identifies the first output blob. Where metadata accompanies blob data, ``_blob_index`` associates it with the query's output blob array. See :doc:`../API-Description` for blob ordering. Choose at least one of ``_ref``, ``results``, ``uniqueids: true``, ``blobs: true``, ``coordinates: true``, ``areas: true``, or ``labels: true``. Missing parent images or failed crop/encoding operations can return ``status: -1``. Metadata-only searches do not need to retrieve the parent image. Invalid parameters, undeclared or incorrectly typed references, and failed output validation return ``status: -1`` with ``info``. A violated ``unique: true`` expectation returns ``status: 3``. A response that exceeds the configured message budget can return ``status: 4``; reduce the result limit or requested data. See :doc:`../Responses` for error envelopes and retry guidance. Examples -------- Find the bounding boxes connected to the image with "unique_id" = 34, and of the label = "Dog": .. TESTED_EXAMPLE: FindBoundingBox_1 .. code-block:: json [{ "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: .. TESTED_EXAMPLE: FindBoundingBox_1_response .. code-block:: json [{ "FindImage": { "blobs_start": 0, "entities": [{ "_blob_index": 0, "_class": "Images" }], "returned": 1, "status": 0 } }, { "FindBoundingBox": { "entities": [{ "_class": "Annotations", "_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: .. TESTED_EXAMPLE: FindBoundingBox_2 .. code-block:: json [{ "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: .. TESTED_EXAMPLE: FindBoundingBox_2_response .. code-block:: json [{ "FindImage": { "blobs_start": 0, "entities": [{ "_blob_index": 0, "_class": "Images" }], "returned": 1, "status": 0 } }, { "FindBoundingBox": { "entities": [{ "_class": "Annotations", "_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": .. TESTED_EXAMPLE: FindBoundingBox_3 .. code-block:: json [{ "FindBoundingBox": { "with_label": "Dog", "constraints": ["$year", "==", 2005], "blobs": true, "as_format": "jpg" } }] Successful response: .. TESTED_EXAMPLE: FindBoundingBox_3_response .. code-block:: json [{ "FindBoundingBox": { "blobs_start": 0, "entities": [{ "_blob_index": 0, "_class": "Annotations" }], "returned": 1, "status": 0 } }]