FindFrame

Find frames that satisfy the specified constraints.

This command enables visual operations, using the operations parameter.

Images are returned as blobs in the array of blobs.

Requires an authenticated user with 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 restriction. Compare stored _label for exact equality.
video_ref	integer 1–100000 / optional	Omitted: no parent-video restriction. Must refer to videos declared earlier in this query; intersect their frames with other filters, including is_connected_to.
blobs	boolean / optional	false; true extracts the selected frames as output image blobs from their parent videos. No input blob is consumed.
as_format	string: jpg, png, tif / optional	png; selects the output image encoding when blobs:true. Stored video data is unchanged.
operations	array of objects / optional	Omitted: no transformations. With blobs:true, apply the shared media operations to extracted frame data before encoding. Operation-specific fields are validated by the operations helper.
frame_numbers	boolean / optional	false; true returns _frame_number when the frame was defined by a frame number. It does not convert other stored position forms.
time_offsets	boolean / optional	false; true returns _time_offset as a formatted time string when stored in that form. It does not convert other stored position forms.
time_fractions	boolean / optional	false; true returns stored _time_fraction when the frame was defined by a fraction. It does not convert other stored position forms.
labels	boolean / optional	false unless results.all_properties:true; true returns _label. Explicit false disables this extra property selection.
in_frame_number_range	object with optional integer start/stop, each 0–9007199254740992 / optional	Omitted: no restriction in this position format. Supplied endpoints are inclusive; missing endpoints are unbounded. Compare the stored position of this kind; no conversion between frame numbers, time offsets, and fractions. Multiple supplied ranges are intersected.
in_time_offset_range	object with optional time-string start/stop / optional	Omitted: no restriction in this position format. Supplied endpoints are inclusive; missing endpoints are unbounded. Compare the stored position of this kind; no conversion between frame numbers, time offsets, and fractions. Multiple supplied ranges are intersected.
in_time_fraction_range	object with optional numeric start/stop, each 0–1 / optional	Omitted: no restriction in this position format. Supplied endpoints are inclusive; missing endpoints are unbounded. Compare the stored position of this kind; no conversion between frame numbers, time offsets, and fractions. Multiple supplied ranges are intersected.

Details

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 video_ref parameter is used, the results can be grouped by the source video. The parameter is ignored if neither is_connected_to nor video_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. Use each entity’s _blob_index to locate its image in the query’s output blob array. Entities selecting the same image can share a blob. A time-based position selects the image displayed at that time; a fractional position is relative to the parent video’s duration. See API Description for blob ordering.

Choose at least one of _ref, results, uniqueids: true, blobs: true, or a true position/label selector. Frame position selectors return positions in the units originally supplied; they do not convert to other units. Set the relevant position selector explicitly; results.all_properties alone does not reliably return position fields.

Missing parent videos, unavailable frame positions, and media decoding failures return status: -1 with an info message. Positions outside the available video data, or excluded by an interval or preview operation, are rejected.

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 frames which has the “topic” property equal to “car chase”, and retrieve “topic” and “movie_title” properties for each frame. Note that the search is performed with no regard to the videos the frames are connected to.

[{
    "FindFrame": {
        "constraints": ["$topic", "==", "car chase"],
        "results": {
            "list": ["topic", "movie_title"]
        }
    }
}]

Successful response:

[{
    "FindFrame": {
        "returned": 1,
        "status": 0,
        "entities": [{
            "topic": "car chase",
            "movie_title": "Megamind"
        }]
    }
}]

Similar to the above, except the search is performed over the frames that are connected to videos that have property “movie_rating” equal to “PG13”:

Find videos with the property “movie_rating” equal to “PG13”, then find frames that are connected to the videos and have property “topic” equal to “car chase”. Returned properties of the frames are “topic” and “movie_title”.

[{
    "FindVideo": {
        "_ref": 1,
        "constraints": ["$movie_rating", "==", "PG13"]
    }
}, {
    "FindFrame": {
        "is_connected_to": {
            "ref": 1
        },
        "constraints": ["$topic", "==", "car chase"],
        "results": {
            "list": ["topic", "movie_title"]
        }
    }
}]

Successful response:

[{
    "FindVideo": {
        "returned": 0,
        "status": 0
    }
}, {
    "FindFrame": {
        "returned": 1,
        "status": 0,
        "entities": [{
            "topic": "car chase",
            "movie_title": "Megamind"
        }]
    }
}]