FindImage ========= Find images that satisfy the specified constraints. The read-only ``_mime_type`` property identifies stored image content. Request it with ``results.list`` or ``results.all_properties``, use it in constraints, or create a property index on it. Retrieval-time ``as_format`` or operations do not change this stored value. 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. See :doc:`../API-Description` for query and blob ordering, and :doc:`../Responses` for response fields and errors. Parameters ---------- .. include:: find_parameters.rst .. list-table:: :header-rows: 1 :widths: 22 18 60 * - Parameter - Type / required - Default and behavior * - ``bounding_box_ref`` - integer 1–100000 / optional - Select the parent images of bounding boxes referenced earlier in the query. * - ``polygon_ref`` - integer 1–100000 / optional - Select the parent images of polygons referenced earlier in the query. * - ``as_format`` - string / optional - Original format when omitted; accepts ``jpg``, ``png``, or ``tif``. * - :ref:`blobs ` - Boolean / optional - ``false``; return encoded images when true. * - ``urls`` - Boolean / optional - ``false``; true requests the stored remote URL. Supply ``blobs: false`` explicitly for metadata-only URL retrieval; omitting ``blobs`` can return an empty URL for remote images. * - ``with_url`` - string / optional - Omitted: no URL restriction. Match a stored URL. * - :ref:`operations ` - array of objects / optional - Omitted: return the original image. Transformations affect returned blobs only. Details ------- Ownership is separate from customer connections. Use ``bounding_box_ref`` or ``polygon_ref`` for parent-image traversal; ``is_connected_to`` follows customer connections. Ownership selectors intersect other supplied filters. The **as_format** parameter can be used to re-encode the image in a format different from the one stored in ApertureDB. The encoding will be performed on-the-fly and will not affect the original image stored in ApertureDB. By default, the images will be returned in their original format. .. include:: url_updates_retention.rst Operations defined in :ref:`operations ` parameter will be performed on-the-fly and will not affect the original image stored in ApertureDB. Set ``"blobs": true`` to return encoded images in the :ref:`array of blobs `. The default is ``false``. This command consumes no input blob. Specify ``results``, ``_ref``, ``uniqueids: true``, or ``blobs: true``; otherwise validation fails. .. include:: group_by_source_details.rst Response and recovery --------------------- ``status`` and ``returned`` describe the command result. Requested metadata appears in ``entities``. When image blobs are returned, ``blobs_start`` locates the first blob in the response list and ``_blob_index`` locates a returned entity's blob. A reference-only lookup can match images while returning no metadata or blobs. * ``status: -1`` can indicate invalid output selection, an unsupported image operation, or failure to retrieve an image. Check the ``info`` message; for remote images also check the URL and :doc:`CreateCredential` settings. * ``status: 3`` can indicate a violated ``unique: true`` expectation. * ``status: 4`` indicates the response-size budget was exceeded. Reduce ``limit``, resize the returned images, or retrieve metadata with ``blobs: false``. See :doc:`AddImage` for ingestion and :doc:`../Responses` for error envelopes and delivery failures. Examples -------- Find images which has the "year_captured" property less than 1970, and resize them to 224x224, and retrieve the "year_captured" property for each image: .. TESTED_EXAMPLE: FindImage_1 .. code-block:: json [{ "FindImage": { "constraints": ["$year_captured", "<=", 1970], "operations": [{ "type": "resize", "width": 224, "height": 224 }], "blobs": true, "results": { "list": ["year_captured"] } } }] Successful response: .. TESTED_EXAMPLE: FindImage_1_response .. code-block:: json [{ "FindImage": { "blobs_start": 0, "entities": [{ "_class": "Images", "year_captured": 1970, "_blob_index": 0 }], "returned": 1, "status": 0 } }] Find all the images connected to an Entity of class "Patient" with a specific "patient_id" property, resize the images to 1024x1024, and encode the images using "png" format: .. TESTED_EXAMPLE: FindImage_2 .. code-block:: json [{ "FindEntity": { "_ref": 1, "with_class": "Patient", "unique": true, "constraints": ["$patient_id", "==", "TCGA-02-0070"] } }, { "FindImage": { "as_format": "png", "operations": [{ "type": "resize", "width": 1024, "height": 1024 }], "blobs": true, "is_connected_to": { "ref": 1 } } }] Successful response: .. TESTED_EXAMPLE: FindImage_2_response .. code-block:: json [{ "FindEntity": { "status": 0, "returned": 0 } }, { "FindImage": { "entities": [{ "_class": "Images", "_blob_index": 0 }], "blobs_start": 0, "returned": 1, "status": 0 } }]