FindPolygon

Find polygons that satisfy the specified constraints.

Pixel data is optionally returned as blobs (encoded images) in the array of blobs.

Any authenticated user can run this command, including users without objects.read permission.

Parameters

Parameter	Type / required	Default and behavior
_ref	integer / optional	Omitted: do not retain a reference for later commands in this query.
unique	Boolean / optional	false; require exactly one match when true.
constraints	expression / optional	Omitted: no property filter; other restrictions still apply.
is_connected_to	object / optional	Omitted: no graph-neighbor restriction.
is_endpoint_of	object / optional	Omitted: no connection-endpoint restriction.
group_by_source	Boolean / optional	false; group matches by the source of a relationship lookup.
per_group	Boolean / optional	false; true requires group_by_source: true and applies sort, offset and limit within each source group.
results	object / optional	Omitted: no requested property projection or aggregate. Select output or retain a reference as described below.
batch	object / optional	Omitted: no distributed result batching.
sort	string, object, or array / optional	Omitted: no explicit property ordering; nearest-neighbor commands have their own distance ordering.
limit	integer 0–2147483647 / optional	Omitted: no explicit result-count limit.
offset	integer 0–2147483647 / optional	0; skip this many matches after sorting.
uniqueids	Boolean / optional	false; include object identifiers when true.

Parameter	Type / required	Default and behavior
with_label	string / optional	Omitted: no label filter. Compare the stored _label for exact equality.
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.
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.
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.

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.

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 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 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:

[{
    "FindImage": {
        "_ref": 1,
        "blobs": false,
        "constraints": ["$guid", "==", 34]
    }
}, {
    "FindPolygon": {
        "image_ref": 1,
        "vertices": true,
        "labels": true,
        "with_label": "Dog",
        "results": {
            "list": ["id"]
        }
    }
}]

Successful response:

[{
    "FindImage": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindPolygon": {
        "entities": [{
            "_label": "Dog",
            "_vertices": [
                [
                    [10.0, 10.0],
                    [10.0, 20.0],
                    [20.0, 10.0]
                ]
            ],
            "id": 42
        }],
        "returned": 1,
        "status": 0
    }
}]

Find the polygons connected to the image with “guid” = 34, and that are inside a given rectangle:

[{
    "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:

[{
    "FindImage": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindPolygon": {
        "entities": [{
            "_label": "Dog",
            "id": 1234
        }],
        "returned": 1,
        "status": 0
    }
}]

Retrieve pixel data from all polygons with the “label” = “dog” and “year” = 2005, encoded as “jpg”:

[{
    "FindImage": {
        "_ref": 1,
        "blobs": false,
        "constraints": ["$id", "==", 1234]
    }
}, {
    "FindPolygon": {
        "image_ref": 1,
        "labels": true,
        "with_label": "Dog",
        "results": {
            "list": ["id"]
        }
    }
}]

Successful response:

[{
    "FindImage": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindPolygon": {
        "entities": [{
            "_label": "Dog",
            "id": 4321
        }],
        "returned": 1,
        "status": 0
    }
}]