AddBoundingBox

Add a new Bounding Box and properties associated with it.

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.
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.
image_ref	integer, 1 through 100000	Required. Uses an earlier compatible image reference in this transaction; forward references, wrong types, and undeclared references are rejected. Creates the parent-image connection. Select a single image when the region must have one parent; insertion does not enforce single-image cardinality.
label	string	Optional. Stored as “None”. Sets the object’s label independently of user properties.
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.
rectangle	object with integer x, y, width, height	Required. All four fields are required when rectangle is present. x and y are nonnegative; width and height are positive; each is at most 2147483647. Replaces the entire rectangle. Insertion does not validate it against image dimensions.

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 image_ref parameter creates the parent-image connection automatically. Use a FindImage with unique: true when exactly one parent image is required. The insertion path does not enforce that cardinality itself.

A rectangle parameter is required, as it indicates the boundaries of the bounding box.

Response and errors

An authenticated session with the objects create permission is required.

The response is an object under AddBoundingBox 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.

Examples

Insert an Image, re-encoding it as a “png”, and 2 BoundingBox objects, and create a connection between the 2 BoundingBox objects and the Image:

[{
    "AddImage": {
        "_ref": 1,
        "format": "png",
        "properties": {
            "description": "dog playing in a park"
        }
    }
}, {
    "AddBoundingBox": {
        "image_ref": 1,
        "label": "Dog",
        "rectangle": {
            "x": 120,
            "y": 50,
            "width": 40,
            "height": 40
        },
        "properties": {
            "label_id": 32
        }
    }
}, {
    "AddBoundingBox": {
        "image_ref": 1,
        "label": "Park",
        "rectangle": {
            "x": 10,
            "y": 20,
            "width": 400,
            "height": 400
        },
        "properties": {
            "label_id": 6
        }
    }
}]

Successful response:

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

Insert an Image and a BoundingBox, and create a connection between the 2 objects, and connect the BoundingBox to an existing Entity of the class “Person” with a specific “unique_id” property:

[{
    "FindEntity": {
        "_ref": 1,
        "with_class": "Person",
        "unique": true,
        "constraints": ["$unique_id", "==", 2341]
    }
}, {
    "AddImage": {
        "_ref": 2,
        "properties": {
            "description": "dog playing in a park"
        }
    }
}, {
    "AddBoundingBox": {
        "image_ref": 2,
        "label": "Dog",
        "rectangle": {
            "x": 120,
            "y": 50,
            "width": 40,
            "height": 40
        },
        "properties": {
            "label_id": 32
        },
        "connect": {
            "ref": 1,
            "class": "PersonInImage"
        }
    }
}]

Successful response:

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