AddImage

Add a new image and properties associated with it.

The image comes from either an encoded image in the array of blobs or a remote url.

Parameters

Parameter	JSON type	Behavior
_ref	integer, 1 through 100000	Optional. Declares a unique reference for later commands in this transaction. When omitted, no reference is available to later commands. If conditional insertion finds existing objects, the reference names those matches.
connect	connection object or array of connection objects	Optional. When omitted, no additional user connections are created. Each object requires an earlier node ref. Optional class chooses a connection class; direction is in or out (default out); properties sets connection properties. Omitted class uses this command’s default connection class. Connections are created only for a newly inserted object.
format	string: jpg, png, or tif	Optional. Preserves the input image format. Re-encodes uploaded content when needed. Rejected with url, even if it equals the remote format.
if_not_found	array expression	Optional. Checks existing objects of this type before insertion. When omitted, no duplicate lookup is performed. A match skips creation, properties, and new connections; status is 2 and _ref names all matches. An empty expression array is invalid.
operations	array of operation objects	Optional. No media operations are applied; an empty array also performs none. Applies operations in order before storing uploaded content. Allowed types: resize, crop, threshold, flip, rotate, transpose. Each operation must satisfy its own parameter contract. Rejected with url, including an empty array.
properties	object mapping property names to values	Optional. When omitted, no user properties are added. Stores booleans, numbers, strings, supported arrays, or single-key _date, _blob, and _json wrappers. Bare null is rejected; property names and wrapped values are validated. See the properties reference for nested value rules.
url	string	Optional. Registers externally stored content at a supported, accessible URL without copying it into managed storage or consuming an input blob. When omitted, one input blob is required in the transaction blob array. URL validation, access, or size/media reads may fail. Presence of format or operations together with url is rejected, including an empty operations array.

Details

The properties object stores key-value pairs on the new object.

The if_not_found condition inserts the object only when no existing object matches the condition.

The connect parameter creates connections between the new object and objects referenced earlier in the transaction.

The format parameter re-encodes an uploaded image when its requested format differs from the original in the array of blobs.

A valid URL registers a remotely stored image without copying its content into ApertureDB. The command consumes no input blob when url is supplied.

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.

The operations run in order before ApertureDB stores the image.

With url, the original content remains in remote storage. format and operations are not permitted during insertion because they would require a local copy or write access to the original remote object.

Response and errors

An authenticated session with the objects create permission is required.

The response is an object under AddImage with integer status. Status 0 means creation succeeded; status 2 means conditional insertion found existing objects. No output blob or created-object count is returned.

Invalid field types, missing required fields, malformed expressions, and invalid references fail validation. Execution failures include a nonzero status and an info message; inspect the transaction response before assuming a mutation succeeded. Input-blob count/order must match the commands that consume blobs. Unreadable remote objects, invalid media, and storage/processing failures can also fail the command.

Examples

Both requests below omit url and therefore require one separate encoded image blob each. Load an image file as bytes and pass [image_bytes] with the JSON command array; see API Description for a complete client call.

Insert an image, save it as png, and apply a threshold operation before storing:

[{
    "AddImage": {
        "properties": {
            "type": "scan",
            "part": "brain"
        },
        "format": "png",
        "operations": [{
            "type": "threshold",
            "value": 155
        }]
    }
}]

Successful response:

[{
    "AddImage": {
        "status": 0
    }
}]

Insert an image as a JPG, rotate 45.6 degrees, and create a connection to a “Patient” referenced using FindEntity:

[{
    "FindEntity": {
        "_ref": 1,
        "with_class": "Patient",
        "constraints": ["$guid", "==", "TCGA-02-0070"]
    }
}, {
    "AddImage": {
        "format": "jpg",
        "operations": [{
            "type": "rotate",
            "angle": 45.6,
            "resize": true
        }],
        "connect": {
            "ref": 1,
            "class": "ScanToPatient",
            "direction": "in"
        }
    }
}]

Successful response:

[{
    "FindEntity": {
        "status": 0,
        "returned": 0
    }
}, {
    "AddImage": {
        "status": 0
    }
}]