.. _FindPolygon: FindPolygon =========== Find polygons that satisfy the specified constraints. Pixel data is optionally returned as blobs (encoded images) in the :ref:`array of blobs `. Any authenticated user can run this command, including users without ``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 polygons with other filters, including is_connected_to. * - :ref:`in_rectangle ` - object / optional - Omitted: no spatial restriction. Require the polygon bounds 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 rectangular crop of the polygon bounds from its 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. * - ``bounds`` - boolean / optional - false unless results.all_properties:true; true returns _bounds with x, y, width, height. results.all_properties:true requests bounds even if bounds:false. * - ``hulls`` - boolean / optional - false; true computes _hulls as an array of convex-hull vertex arrays, one for each polygon component. * - ``vertices`` - boolean / optional - false; true returns _vertices as an array of polygon-component vertex arrays. * - ``decompositions`` - boolean / optional - false; true returns _decompositions as an array of convex-piece vertex arrays across all polygon components. * - ``areas`` - boolean / optional - false unless results.all_properties:true; true returns stored _area in square pixels. results.all_properties:true also requests it when areas:false. * - ``labels`` - boolean / optional - false unless results.all_properties:true; true returns _label. results.all_properties:true also requests it when labels:false. 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 polygon. 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 rectangular region defined by the polygon's bounds 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``, or a true geometry/label selector. Missing parent images or failed crop/encoding operations can return ``status: -1``. Requesting ``results.all_properties`` selects stored properties but does not automatically compute ``_hulls``, ``_vertices``, or ``_decompositions``; set those selectors explicitly when needed. 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 polygons connected to the image with "guid" = 34, and of the label = "Dog". Return boundary geometry and labels without pixel data: .. TESTED_EXAMPLE: FindPolygon_1 .. code-block:: json [{ "FindImage": { "_ref": 1, "blobs": false, "constraints": ["$guid", "==", 34] } }, { "FindPolygon": { "image_ref": 1, "vertices": true, "labels": true, "with_label": "Dog", "results": { "list": ["id"] } } }] Successful response: .. TESTED_EXAMPLE: FindPolygon_1_response .. code-block:: json [{ "FindImage": { "returned": 0, "status": 0 } }, { "FindPolygon": { "entities": [{ "_label": "Dog", "_vertices": [ [ [10.0, 10.0], [10.0, 20.0], [20.0, 10.0] ] ], "id": 42, "_class": "Polygons" }], "returned": 1, "status": 0 } }] Find the polygons connected to the image with "guid" = 34, and that are inside a given rectangle: .. TESTED_EXAMPLE: FindPolygon_2 .. code-block:: json [{ "FindImage": { "_ref": 1, "blobs": false, "constraints": ["$id", "==", 34] } }, { "FindPolygon": { "image_ref": 1, "labels": true, "in_rectangle": { "x": 100, "y": 100, "width": 500, "height": 500 }, "results": { "list": ["id"] } } }] Successful response: .. TESTED_EXAMPLE: FindPolygon_2_response .. code-block:: json [{ "FindImage": { "returned": 0, "status": 0 } }, { "FindPolygon": { "entities": [{ "_class": "Polygons", "_label": "Dog", "id": 1234 }], "returned": 1, "status": 0 } }] Retrieve pixel data from all polygons with the "label" = "dog" and "year" = 2005, encoded as "jpg": .. TESTED_EXAMPLE: FindPolygon_3 .. code-block:: json [{ "FindImage": { "_ref": 1, "blobs": false, "constraints": ["$id", "==", 1234] } }, { "FindPolygon": { "image_ref": 1, "labels": true, "with_label": "Dog", "results": { "list": ["id"] } } }] Successful response: .. TESTED_EXAMPLE: FindPolygon_3_response .. code-block:: json [{ "FindImage": { "returned": 0, "status": 0 } }, { "FindPolygon": { "entities": [{ "_class": "Polygons", "_label": "Dog", "id": 4321 }], "returned": 1, "status": 0 } }]