.. _AddImage: AddImage ======== Each image stores a read-only ``_mime_type`` property detected from its stored content, such as ``image/jpeg``, ``image/png``, or ``image/tiff``. When ingestion operations or ``format`` convert the image, this property describes the converted image. Remote media types are determined from the content; the URL extension does not determine the MIME type. Add a new image and properties associated with it. The image comes from either an encoded image in the :ref:`array of blobs ` or a remote **url**. Parameters ---------- ``class`` is required; it names this object's application class within its type. .. list-table:: :header-rows: 1 :widths: 15 25 60 * - Parameter - JSON type - Behavior * - :ref:`_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. * - :ref:`connect ` - connection object or array of connection objects - Optional. When omitted, no additional user connections are created. Each object requires an earlier node ref. A customer class is required; direction is in or out (default out); properties sets connection properties. Connections are created only for a newly inserted object. * - :ref:`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. * - :ref:`if_not_found ` - array expression - Optional. Checks existing objects of this exact type/class 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. * - :ref:`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. * - :ref:`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. * - :ref:`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 ------- .. include:: add_details.rst The **format** parameter re-encodes an uploaded image when its requested format differs from the original in the :ref:`array of blobs `. A :ref:`valid URL ` registers a remotely stored image without copying its content into ApertureDB. The command consumes no input blob when **url** is supplied. .. include:: url_updates_retention.rst The :ref:`operations ` run in order before ApertureDB stores the image. .. include:: url_operations.rst 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 :doc:`../API-Description` for a complete client call. Insert an image, save it as png, and apply a threshold operation before storing: .. TESTED_EXAMPLE: AddImage_1 .. code-block:: json [{ "AddImage": { "class": "Images", "properties": { "type": "scan", "part": "brain" }, "format": "png", "operations": [{ "type": "threshold", "value": 155 }] } }] Successful response: .. TESTED_EXAMPLE: AddImage_1_response .. code-block:: json [{ "AddImage": { "status": 0 } }] Insert an image as a JPG, rotate 45.6 degrees, and create a connection to a "Patient" referenced using :ref:`FindEntity `: .. TESTED_EXAMPLE: AddImage_2 .. code-block:: json [{ "FindEntity": { "_ref": 1, "with_class": "Patient", "constraints": ["$guid", "==", "TCGA-02-0070"] } }, { "AddImage": { "class": "Images", "format": "jpg", "operations": [{ "type": "rotate", "angle": 45.6, "resize": true }], "connect": { "ref": 1, "class": "ScanToPatient", "direction": "in" } } }] Successful response: .. TESTED_EXAMPLE: AddImage_2_response .. code-block:: json [{ "FindEntity": { "status": 0, "returned": 0 } }, { "AddImage": { "status": 0 } }]