FindPolygon

Find polygons that satisfy the specified constraints.

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_ref: Reference to an image within the transaction (either the result of a FindImage or an AddImage) from which the corresponding polygon will be retrieved.
• [optional] blobs: indicates whether pixel data will be returned as part of the response (Default: false).
• [optional] bounds: indicates whether bounding boxes of the polygons will be returned as part of the response (Default: false). If set, the bounds will be returned as a rectangle.
• [optional] hulls: indicates whether the convex hulls of the polygons will be returned as part of the response (Default: false). If set, the hulls will be returned as polygons.
• [optional] vertices: indicates whether the vertices of the polygon regions will be returned as part of the response (Default: false). If set, the vertices will be returned as polygons.
• [optional] decompositions: indicates whether the convex decompositions of the polygons will be returned as part of the response (Default: false). If set, decompositions will be returned as polygons.
• [optional] areas: indicates whether to return the areas (in pixels) enclosed by the polygons (default: false).
• [optional] labels: indicates whether polygon labels 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 pixel data blobs ["jpg", "png"], if "blobs" is set. By default, they 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] results
• [optional] batch

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 constraint by the constraints.

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. The parameter is ignored if is_connected_to is absent. It is set to false by default.

Examples

Find the polygons connected to the image with "guid" = 34, and of the label = "Dog":

    [{
        "FindImage": {
            "_ref": 1,
            "blobs": false,       // Do not retrieve pixel data
            "constraints": {
                "guid": ["==", 34]
            }
        }
    }, {
        "FindPolygon": {
            "image_ref": 1,
            "vertices": true,     // Retrieve boundary geometry
            "labels": true,       // Retrieve label
            "with_label": "Dog",  // Filter by label
            "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, // Do not retrieve pixel data
            "constraints": {
                "id": ["==", 34]
            }
        }
    }, {
        "FindPolygon": {
            "image_ref": 1,
            "labels": true,   // Retrieve label
            "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, // Do not retrieve pixel data
            "constraints": {
                "id": ["==", 1234]
            }
        }
    }, {
        "FindPolygon": {
            "image_ref": 1,
            "labels": true,       // Retrieve label
            "with_label": "Dog",  // Filter by label
            "results": {
                "list": ["id"]
            }
        }
    }]

Successful response:

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