FindImage

Find images 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. See API Description for query and blob ordering, and Responses for response fields and errors.

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
as_format	string / optional	Original format when omitted; accepts jpg, png, or tif.
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; with blobs omitted, the current implementation can return an empty URL for remote images.
with_url	string / optional	Omitted: no URL restriction. Match a stored URL.
operations	array of objects / optional	Omitted: return the original image. Transformations affect returned blobs only.

Details

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.

Content referenced by url can change outside ApertureDB or expire under the remote storage service’s retention policy. A Find* command returns an error if the remote content is no longer accessible.

Operations defined in 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 array of blobs. The default is false. This command consumes no input blob. Specify results, _ref, uniqueids: true, or blobs: true; otherwise validation fails.

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. The parameter is ignored if is_connected_to is absent. It is set to false by default.

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 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 AddImage for ingestion and 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:

[{
    "FindImage": {
        "constraints": ["$year_captured", "<=", 1970],
        "operations": [{
            "type": "resize",
            "width": 224,
            "height": 224
        }],
        "blobs": true,
        "results": {
            "list": ["year_captured"]
        }
    }
}]

Successful response:

[{
    "FindImage": {
        "blobs_start": 0,
        "entities": [{
            "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:

[{
    "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:

[{
    "FindEntity": {
        "status": 0,
        "returned": 0
    }
}, {
    "FindImage": {
        "blobs_start": 0,
        "returned": 1,
        "status": 0
    }
}]