.. _FindFrame: FindFrame ========= Find frames that satisfy the specified constraints. This command enables visual operations, using the :ref:`operations parameter `. Images are returned as blobs in the :ref:`array of blobs `. Requires an authenticated user with ``objects.read`` permission. Parameters ---------- .. include:: find_parameters.rst .. list-table:: :header-rows: 1 :widths: 22 23 55 * - Parameter - Type / required - Default and behavior * - :ref:`with_label ` - string / optional - Omitted: no label restriction. Compare stored _label for exact equality. * - :ref:`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. * - :ref:`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. * - :ref:`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. * - :ref:`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. * - :ref:`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. * - :ref:`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 ------- .. include:: group_by_source_details_video_ref.rst 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 :doc:`../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 :doc:`../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. .. TESTED_EXAMPLE: FindFrame_1 .. code-block:: json [{ "FindFrame": { "constraints": ["$topic", "==", "car chase"], "results": { "list": ["topic", "movie_title"] } } }] Successful response: .. TESTED_EXAMPLE: FindFrame_1_response .. code-block:: json [{ "FindFrame": { "returned": 1, "status": 0, "entities": [{ "_class": "Frames", "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". .. TESTED_EXAMPLE: FindFrame_2 .. code-block:: json [{ "FindVideo": { "_ref": 1, "constraints": ["$movie_rating", "==", "PG13"] } }, { "FindFrame": { "video_ref": 1, "constraints": ["$topic", "==", "car chase"], "results": { "list": ["topic", "movie_title"] } } }] Successful response: .. TESTED_EXAMPLE: FindFrame_2_response .. code-block:: json [{ "FindVideo": { "returned": 0, "status": 0 } }, { "FindFrame": { "returned": 1, "status": 0, "entities": [{ "_class": "Frames", "topic": "car chase", "movie_title": "Megamind" }] } }]