RegionIoU

Compute pairwise intersection-over-union values for referenced regions.

Requires objects.read permission. No input or output blobs are used. Both bounding-box and polygon references are supported.

Parameters

Parameter	Type / required	Default and behavior
roi_1	integer / required	Reference to bounding boxes or polygons declared earlier in this query; no default.
roi_2	integer / conditional	Exactly one of roi_2, rectangle, or polygons is required. A prior region reference supplies the second set.
rectangle	object / conditional	Alternative second region: x, y, width, height integers. x/y are nonnegative and width/height are positive; values must fit signed 32-bit integers.
polygons	array of polygons / conditional	Alternative second region: nonempty array of polygons, each containing at least three numeric [x, y] vertices; see polygons.

Details

The first referenced set defines matrix rows; the second set defines columns. A literal rectangle or polygon collection is one region and therefore produces one column. The result measures intersection area divided by union area. Regions need not belong to the same image, so use compatible coordinates when selecting them.

Response and recovery

Success returns status: 0 and IoU, a two-dimensional numeric array. There is no returned count or entity list in this response. Each element corresponds to one row/column pair; nonoverlapping regions have value zero.

Failure or empty result	Cause and recovery
No or multiple second-region selectors	Specify exactly one of roi_2, rectangle, or polygons.
roi_1 returned no results or roi_2 returned no results	Ensure each reference selects at least one bounding box or polygon.
Invalid rectangle, polygon, or reference	Correct the shape coordinates and use a region reference declared earlier in the query.

See Responses for validation, authentication, and permission error envelopes. Command errors use a negative status and an info message.

Examples

These complete JSON requests assume the named image and regions already exist. The displayed responses illustrate the shape; identifiers and overlap values depend on the stored geometry.

Within image id: 1234, select skateboard bounding boxes and dog polygons, then compute a matrix with one row per skateboard and one column per dog:

[
    {
        "FindImage": {
            "_ref": 1,
            "blobs": false,
            "constraints": [
                "$id",
                "==",
                1234
            ]
        }
    },
    {
        "FindBoundingBox": {
            "_ref": 2,
            "image_ref": 1,
            "with_label": "skateboard",
            "blobs": false,
            "uniqueids": true
        }
    },
    {
        "FindPolygon": {
            "_ref": 3,
            "image_ref": 1,
            "with_label": "dog",
            "blobs": false,
            "uniqueids": true
        }
    },
    {
        "RegionIoU": {
            "roi_1": 2,
            "roi_2": 3
        }
    }
]

For two skateboards and three dogs, a response can look like this:

[
    {
        "FindImage": {
            "status": 0,
            "returned": 0
        }
    },
    {
        "FindBoundingBox": {
            "entities": [
                {
                    "_uniqueid": "20.1.100"
                },
                {
                    "_uniqueid": "20.2.200"
                }
            ],
            "returned": 2,
            "status": 0
        }
    },
    {
        "FindPolygon": {
            "entities": [
                {
                    "_uniqueid": "21.1.300"
                },
                {
                    "_uniqueid": "21.2.400"
                },
                {
                    "_uniqueid": "21.3.500"
                }
            ],
            "returned": 3,
            "status": 0
        }
    },
    {
        "RegionIoU": {
            "status": 0,
            "IoU": [
                [
                    0.0,
                    0.1875,
                    0.0
                ],
                [
                    0.2012,
                    0.0,
                    0.0
                ]
            ]
        }
    }
]

Nonzero values identify overlapping pairs. This example has no overlap in the third column, so the third dog overlaps neither skateboard.

Select the polygon with id: 2342 and compare it with a literal square. This request expects exactly one matching polygon:

[
    {
        "FindPolygon": {
            "_ref": 1,
            "constraints": [
                "$id",
                "==",
                2342
            ],
            "unique": true,
            "blobs": false
        }
    },
    {
        "RegionIoU": {
            "roi_1": 1,
            "polygons": [
                [
                    [
                        10,
                        10
                    ],
                    [
                        30,
                        10
                    ],
                    [
                        30,
                        30
                    ],
                    [
                        10,
                        30
                    ]
                ]
            ]
        }
    }
]

If the stored polygon is the same square, the response is:

[
    {
        "FindPolygon": {
            "status": 0,
            "returned": 0
        }
    },
    {
        "RegionIoU": {
            "status": 0,
            "IoU": [
                [
                    1.0
                ]
            ]
        }
    }
]