group_by_source

When is_connected_to parameter is specified in a Find* command the result is a set of objects connected to the referenced Find* command by connections as defined by the is_connected_to parameter. group_by_source offers a way to group the resulting objects by their source entity. This parameter is set to False by default and objects are returned in one flat array.

group_by_source can also be used in conjunction with Find* commands that use either the image_ref (e.g. FindBoundingBox, FindPolygon) or video_ref (e.g. FindFrame, FindClip) parameter in order to group the results by the source image or video.

Examples

For instance, we can search for entities of class "Person" connected to other entities of class "Person" and with "name" as any of "Jane", "Keya", or "Stana", as follows and return them grouped by their origin entities. In this case, the first FindEntity returns two matches, namely "Keya" and "Stana". "Madhuri" is returned as the neighbor of the entity with "name" as "Keya" in one array, followed by "Brie" and "Scarlett" which are then returned in another array where they correspond to the source entity with "name" as "Stana".

[{
    "FindEntity": {
        "with_class": "Person",
        "_ref": 1234,
        "uniqueids": true,
        "constraints": {
            "name": [
                "in",
                ["Jane", "Keya", "Stana"]
            ]
        },
        "results": {
            "list": ["name"]
        }
    }
}, {
    "FindEntity": {
        "with_class": "Person",
        "is_connected_to": {
            "ref": 1234,
            "connection_class": "BestFriendForever"
        },
        "group_by_source": true,
        "results": {
            "list": ["name"]
        }
    }
}]

Successful response:

[{
    "FindEntity": {
        "entities": [{
            "_uniqueid": "6.0.59676",
            "name": "Jane"
        }, {
            "_uniqueid": "6.1.59676",
            "name": "Keya"
        }, {
            "_uniqueid": "6.3.59676",
            "name": "Stana"
        }],
        "returned": 3,
        "status": 0
    }
}, {
    "FindEntity": {
        "entities": {
            "6.0.59676": [],
            "6.1.59676": [{
                "name": "Madhuri"
            }],
            "6.3.59676": [{
                "name": "Brie"
            }, {
                "name": "Scarlett"
            }]
        },
        "group_by_source": true,
        "returned": 3,
        "status": 0
    }
}]