1 Introduction

This is the API integration document for the VCAcore Video Analytics system.

2 REST API Introduction

2.1 Configuration Tree

The REST API of VCAcore is used by Core’s web UI to configure the web backend.

The VCAcore REST API allows the user to change its configuration tree, which is where the entire VCAcore configuration is stored. The configuration tree can be accessed using the URL below:

http://SERVER_IP:PORT/api.json

The VCAedge configuration tree is also available via REST API. The configuration tree can be accessed using the URL below:

http://CAMERA_IP/cgi-bin/admin/vca-api/api.json

2.2 Authentication

The REST API of VCAcore uses Digest Authentication.

Include an Authorisation header in HTTP requests, specifying the Digest scheme and parameters.

2.3 Interacting with the Configuration

2.3.1 Adding Objects to the Configuration Tree

To add an object to the configuration, send a POST request to the appropriate endpoint for the type of object you are adding.

For example, to add an element:

POST the element to /api/elements with the following payload:

{
    "typename": "rtsp",
    "location": "rtsp://192.168.1.1/stream",
    "user_id": "admin",
    "user_pw": "password",
    "do_rtsp_keep_alive": "FALSE",
    "protocols": "7",
    "name": "MY_RTSP_STREAM_1"
}

Response:

{
    "index": 2
}

The response is the index of the newly created object in the configuration tree, in this case the RTSP element at /api/elements/2. This index can be used as a reference to update this object.

It is not necessary to include all the properties of an object in the JSON payload of the POST request. Where a property is not specified, a default value will be used. For objects which have a typename property, this property is required.

2.3.2 Deleting Objects from the Configuration Tree

To delete an object to the configuration, send a DELETE request to the appropriate endpoint for the object you are deleting. When deleting, the index of the object must be used in the URL.

For example, to delete element 0:

DELETE request to /api/elements/0.

The response will contain the object that is being deleted:

{
    "typename": "file",
    "name": "",
    "location": "vegas.mp4"
}

Take care when deleting objects from the configuration as the REST API does not check for dependencies. For example, removing an element object used by a channel object is not prohibited. As such, the channel object will remain in the configuration until manually removed.

2.3.3 Modifying Properties in the Configuration Tree

Any property can be modified by sending the appropriate PUT request to the full path of the property, with the desired value in the payload. For example, if you wanted to change the name property on the element that was just created, you would send a PUT request to /api/elements/2/name with the following payload:

"New Name"

It is also possible to update multiple properties in one request by sending a PUT request to the parent object. In this example, you could send a PUT request to /api/elements/2 with the following payload:

{
    "user_id": "root",
    "user_pw": "pass",
    "name": "New Name"
}

These methods can be applied to any object in the api.json.

2.3.4 Getting Properties in the Configuration Tree

Any or all of the configuration tree can be retrieved from the REST API by sending a GET request to the desired endpoint. For example, sending a ‘GET’ request to /api/elements/2/ would return:

{
    "typename": "rtsp",
    "location": "rtsp://192.168.1.1/stream",
    "user_id": "root",
    "user_pw": "pass",
    "do_rtsp_keep_alive": "FALSE",
    "protocols": "7",
    "name": "New Name"
}

Additionally, the entire configuration can be exported by sending a GET request to /api.

2.3.5 Importing the Configuration Tree

The entire configuration tree can be imported using the REST API by sending a POST request to /api/import. The payload should be a JSON object containing the entire configuration tree, as retrieved by sending a GET request to /api.

It is possible to edit and modify this JSON object before upload.

When performing an import, the whole application will be restarted, causing a break in analytics processing.

2.3.6 Error Handling

When a request was successful, the VCAcore web server responds with a __2xx__ code.

Requests that add an object using POST will also have the index of the newly-created object in the response, as shown below:

{
    "index": 4
}

When a request has failed, the web server returns a __4xx__ or __5xx__ error code.

Additionally, the web server will return a descriptive error string that can be used to diagnose the problem. The error is returned as an object with an error property, and the error string as its value:

{
    "error": "An error has occurred."
}

2.3.7 HTTP Request Headers

It is a requirement to add the Content-Type: application/json header to all REST API requests that contain JSON data, which are PUT and POST. Requests that return data (GET, POST, and optionally DELETE) should contain the Accept header set to application/json or */*. Additionally, the GET request can specify the Accept header to application/json+schema instead, in which case, instead of returning the configuration object directly, it will return its schema.

2.4 Custom Objects

2.4.1 Point Object

A point object represents a point in 2D space. Coordinate space orientation for a 2D point is:

• "x": 0 as the left of the camera field of view
• "y": 0 as the bottom of the camera field of view

An example point object is given below:

{
    "x": 200,
    "y": 400
}

The properties of a point object are as follows:

2.4.2 Colour Object

A colour object represents an RGBA colour value An example colour object is given below:

{
    "r": 100,
    "g": 200,
    "b": 140,
    "a": 90
}

The properties of a colour object are as follows:

2.5 Licenses

2.5.1 License Method

To specify which licensing method this instance of VCAcore is using, simply send a PUT request to /api/licenses with a payload containing the method type. A sample payload is given below:

{
    "server": "cloud"
}

VCAcore will attempt to connect using the new license method when the required fields are populated.

2.5.2 Cloud API Key (cloud)

To specify a Cloud Licensing API key for this instance of VCAcore to use, simply send a PUT request to /api/licenses/cloud. Only utilised when licensing server is "cloud". A sample payload is given below:

{
    "api_key": "4a884a88-4a88-4a88-4a88-4a884a884a88"
}

VCAcore will attempt to connect using the new API key automatically.

2.5.3 License Server (local)

To specify which License Server this instance of VCAcore is connected to, simply send a PUT request to /api/licenses/daemon. Only applies when licensing server is "local". A sample payload is given below:

{
    "address": "192.168.0.27",
    "port": 15769
}

VCAcore will attempt to connect using the new connection settings automatically.

2.5.3.1 Adding a License

To add a license pack to VCAcore, simply send a PUT request to /api/licenses/activate. Only applies when licensing server is "local". A sample payload is given below:

Note: The license string provided below is invalid. You will need to purchase a license for your hardware GUID.

"43214321EDFAEFDEAFDEAFDEAFDEADFADAAEEADAFDEAFEDA"

2.5.3.2 Retrieving a License

Available license packs can be retrieved by sending a GET request to /api/licenses/vca.json Only applies when licensing server is "local".

"1": {
    "license": "198704FFFFFFFFAC....",
    "token": "",
    "name": "ProAI 60ch Enterprise",
    "code": 6535,
    "channels": 60,
    "used_channels": 2,
    "zones": 255,
    "rules": 255,
    "counters": 255,
    "evaluation": false,
    "expired": false,
    "days_remaining": 0,
    "suspended": false,
    "features": [
        "presence",
        "enter",
        "exit",
        "appear",
        "disappear",
        "stopped",
        ...
    ]
}

2.5.3.3 Retrieving the Hardware Code

To retrieve the hardware code for the License Server, you need to send a GET request to /api/hardware/guid.json Only applies when licensing server is "local". The GUID is returned as a string, as shown below:

"F60492388FF8030C561B8C1505567B6C5687FAAA254D15FFB1E930D0D4905EA1"

3 REST API Channels

3.1 Elements

There are two types of elements supported by VCAcore - file and RTSP elements. Elements are inputs to channels, and must be added before a channel is created.

3.1.1 Adding an RTSP Element

An RTSP element may be created added by sending a POST request to /api/elements endpoint. A sample RTSP element is shown below:

{
    "typename": "rtsp",
    "location": "",
    "user_id": "",
    "user_pw": "",
    "do_rtsp_keep_alive": "FALSE",
    "protocols": "7",
    "sync_to_rtcp_sr_time": "FALSE",
    "tls_validation_flags": "127",
    "name": ""
}

The tls_validation_flags only apply to RTSP sources with a location starting with rtsps://. The value is made up of seven flags represented as an 8-bit Integer. The last bit is not used and should always be 0. Enabled flags are set to 1, requiring the TLS certificate of that RTSPS source to have no errors relating to that check. Disabled flags are set to 0, allowing errors relating to that check to be ignored. The following mapping outlines the checked flag and the corresponding bit location:

3.1.2 Adding a File Element

An RTSP element may be created by sending a POST request to the api/elements endpoint. A sample file element is shown below:

{
    "typename": "file",
    "name": "",
    "location": "las-vegas.mp4"
}

3.2 Channels

Once an element has been added, it can be linked to a channel. The channel object specifies channel properties including what tracker and algorithms are to be run. The parameters for the algorithms and trackers is also contained in this object and should be defined for each channel. For a channel to begin processing, a valid license code must be assigned to the channel.

3.2.1 Adding a Channel

Once a file or RTSP element has been added, and its index is known, this index can be used to link it to a channel. A channel may be added by sending a POST request to /api/channels. A sample channel object is shown below:

{
    "name": "Main Park",
    "description": "CH08334",
    "enabled": true,
    "input": 5,
    "output": null,
    "licenses": [
        6535,
        8210
    ],
    "event_retrigger_time": 5,
    "crop": {
        "top_left": {
            "x": 0,
            "y": 0
        },
        "bottom_right": {
            "x": 65535,
            "y": 65535
        }
    },
    "tracking_engine": "object_tracker",
    "tracker": {
        "stationary_time": 5000,
        "stationary_hold_on_time": 60000,
        "minimum_object_size": 10,
        "detection_point": 0,
        "sensitivity_threshold": 4,
        "require_initial_movement": true
    },
    "calibration": {
        "enabled": false,
        "height": 4,
        "tilt": 50,
        "fov": 40,
        "roll": 0,
        "pan": 0,
        "location": {
            "latitude": 51.00973709106445,
            "longitude": -0.0025509810447693,
            "elevation": 10
        },
        "orientation": 30
        "horizon": false,
        "grid": {
            "enabled": true,
            "stroke": {
                "r": 115,
                "g": 210,
                "b": 22,
                "a": 1
            },
            "fill": {
                "r": 136,
                "g": 138,
                "b": 133,
                "a": 0
            },
            "spacing": 2
        }
    },
    "calibration_filter": {
        "enabled": false
    },
    "tamper": {
        "enabled": false,
        "alarm_timeout": 20000,
        "area_threshold": 40,
        "low_light": false
    },
    "scene_change": {
        "mode": 1,
        "alarm_timeout": 3000,
        "area_threshold": 40
    },
    "annotation": {
        "zones": false,
        "objects": true,
        "class": false,
        "height": false,
        "speed": false,
        "area": false,
        "ticker": true,
        "dl_class": true,
        "system_message": true,
        "line_counters": true,
        "counters": true,
        "colour_signature": true,
        "tracker_internal_state": false,
        "faces": false,
        "alarmed_only": false,
        "position": true,
        "interactions": true,
        "tamper": true
    },
    "classification": [
        {
            "name": "Person",
            "area": {
                "min": 5,
                "max": 20
            },
            "speed": {
                "min": 0,
                "max": 20
            }
        },
        {
            "name": "Vehicle",
            "area": {
                "min": 40,
                "max": 1000
            },
            "speed": {
                "min": 0,
                "max": 200
            }
        },
        {
            "name": "Clutter",
            "area": {
                "min": 0,
                "max": 4
            },
            "speed": {
                "min": 0,
                "max": 50
            }
        },
        {
            "name": "Group Of People",
            "area": {
                "min": 21,
                "max": 39
            },
            "speed": {
                "min": 0,
                "max": 20
            }
        }
    ],
    "dl_classifier": {
        "enabled": true,
    },
    "dl_accessory_detector": {
        "enabled": false
    },
    "fall": {
        "enabled": false
    },
    "aggressive_behaviour": {
        "enabled": false
    },
    "pose": {
        "enabled": false
    },
    "optical_flow": {
        "enabled": true
    },
    "colour_signature": {
        "enabled": false,
        "max_colours": 4
    }, 
    "generate_features": {
        "enabled": true,
        "interval": 1000
    },
    "stabilisation": {
        "enabled": false
    },
    "user_data": [],
}

Below is a list of properties of a channel object

Certain channel properties and objects will only apply when specific trackers are specified in tracking_engine. In such cases the applicable tracker(s) will be noted below the object.

The following are the properties of a crop object:

The following are the properties of a tracker object, properties apply to a specific tracking_engine:

Values in this object apply to select trackers which have been highlighted per property.

The following are the properties of a calibration object:

Below is a list of the properties of the location object:

Below is a list of the properties of the grid object:

The following are the properties of a calibration_filter object:

Below is a list of the properties of the tamper object:

Values in this object apply to all trackers.

Below is a list of the properties of the scene_change object:

Values in this object only apply to the object_tracker.

Below is a list of the properties of the annotation object:

Values in this object apply to all trackers, unless specifically highlighted.

Below is a list of the properties of the classification object:

Values in this object only apply to the object_tracker

Below is a list of the properties of the threshold object:

Channel algorithm objects allow the use of non-tracker algorithms without configuring the corresponding observable. Adding and removing observables will continue to enable and disable non-tracker algorithms. The algorithm state will be reflected in the channel algorithm objects as this happens.

It is recommended that when events are required, rely on the observables to manage the algorithms. If only algorithm metadata is required and there is no application for the observable events, then management of the algorithms is best done via the channel object.

As this provides two methods to enable and disable an algorithm, a user should be aware of the relationship between algorithm switches and the observable behaviour. There are a few scenarios to be aware of:

1. User enables and disables an algorithm in the channel object directly. As there are no observables there will be no events, the algorithms metadata will be inserted into the metadata streams. E.g. fall: Person objects will have "vca.meta.data.object.Fall" metadata when detected.

2. User adds and removes observables linked to the channel. Both metadata and events will be present in the metadata streams. When the first observable of a given type is added, the algorithm is enabled in the channel object When the last is removed the algorithm is disabled. E.g. fall: Person objects will have "vca.meta.data.object.Fall" metadata when detected, and the fall observable will generate event metadata. Actions associated with that fall observable will be triggered.

3. User adds a corresponding observable and then disables the algorithm in the channel object. This will effectively disable both the metadata and events and leave a zombie observable that is not performing any use. E.g.fall: Person objects can not have "vca.meta.data.object.Fall" metadata, and the fall observable will never generate event metadata. Associated actions with that fall observable can never be triggered.

Below is a list of the properties of the dl_classifier object:

Values in this object only apply to the object_tracker.

Below is a list of the properties of the dl_accessory_detector object:

Values in this object only apply to the dl_skeleton_tracker.

Below is a list of the properties of the fall object:

Values in this object only apply to the dl_skeleton_tracker.

Below is a list of the properties of the aggressive_behaviour object:

Values in this object apply to all trackers.

Below is a list of the properties of the pose object:

Values in this object only apply to the dl_skeleton_tracker.

Below is a list of the properties of the optical_flow object:

Values in this object only apply to the dl_object_tracker.

Below is a list of the properties of the colour_signature object:

Values in this object apply to all trackers.

Below is a list of the properties of the generate_features object:

Values in this object only apply to the dl_object_tracker, dl_people_tracker and dl_skeleton_tracker.

Below is a list of the properties of the stabilisation object:

Please Note Stabilisation is currently not available in the VCAcore backend. API requests to this parameter will continue to be valid and saved in the VCAcore configuration, but the feature itself will not work.

3.2.2 Setting a License

A license code is set on a channel by sending a PUT request to /api/channels/0/licenses endpoint. A sample request is shown below:

[
    6535,
    8210
]

A license is assigned to a channel based on its code. The code signifies to VCAcore which license type to use with a channel and therefore which features to enable. For example 6535 is a ProAI license type and unlocks all the features associated with the ProAI license. More than one license code can be specified to allow for licenses with different features to be assigned to a single channel. VCAcore will attempt to assign the requested licenses to the channel if they are available. If any of the requested licenses are not available, i.e. have not been added to VCAcore or have had all available channels used, then no licenses will be assigned. See Retrieving a License for how to get which licenses codes are available.

3.2.3 Channel Snapshots

A snapshot API is provided which will provide a JPEG encoded image from a defined channel. The resolution of the JPEG will be defined by the input resolution of the stream. A snapshot can be retrieved by sending a GET request to the snapshot endpoint:

http://SERVER_IP:PORT/snapshot/CHANNEL_ID/latest?original=0

It is a requirement to add the Content-Type: image/jpeg header to all requests to the snapshot API. The query parameter original, defines if the returned image will have currently enabled annotations for that channel present or not.

If the parameter is not specified, original defaults to 0, and enabled annotations for that channel will be present in the image.

The snapshot service also supports scaling down snapshots from the original size. Scaling an image up is not possible with this service. The max_width and max_height parameters define ways to specify a dimension and scale. Scaled images always maintain the same aspect ratio, meaning both parameters are never required.

For example, if the input image is 720×480. A snapshot request with the following would return an image half the input size, with no annotations for that channel present.

http://SERVER_IP:PORT/snapshot/CHANNEL_ID/latest?original=1&max_height=240

If both parameters are given, the scale service will honour the lower scaled dimension. For example, if the input image is 720×480. A snapshot request with the following would return an image half the input size, with currently enabled annotations for that channel present.

http://SERVER_IP:PORT/snapshot/CHANNEL_ID/latest?&max_width=600&max_height=240

In this case the max_width is ignored as the max_height parameter results in a smaller scaled image.

When a snapshot API request is sent to VCAcore, the JPEG image is generated on demand. JPEG encoding is a resource intensive process and therefore this API is not designed for streaming at high frame rates. As such it is advised that calls made to this API are done so sparingly.

4 REST API Observables and Other Sources

4.1 Overview

An observable is an object which monitors the metadata and generates an event when specific triggers are met. Commonly, observables are used to represent rules, which are associated with a channel, that fires an event when a specific condition is met by objects tracked in that channel (e.g. Presence or Dwell).

An observable can also represent one of VCAcore’s other sources, these work at a global, rather than channel, level triggering events when a specific global trigger is detected (e.g. VCAcore being Armed or when a scheduled time passes).

Observables can be linked to actions, so that when an event is generated by an observable, an action is performed.

4.1.1 General Concepts

To add an observable, send a POST request to the /api/observables endpoint. Please use the method mentioned earlier to add this element. A sample Presence observable is shown below:

{
    "typename": "vca.observable.Presence",
    "channel": 0,
    "zone": 4294967295,
    "name": "Presence 5",
    "triggers_action": true
}

Note: The value 4294967295 is a sentinel value for null. When present it indicates that the input or zone is invalid.

Below is a list of properties that are common to all observables:

For a complete overview of observable types (Basic Rules, Filters, Conditional Rules and Other Sources), including their function and use cases, please see the full VCAcore Manual.

Many observables have an input, a reference to another observable which serves as a trigger. In all cases, an observable’s input cannot be itself, or a cyclical dependency will be created what will cause abnormal behaviour.

What follows is a list of all the supported types of observables in VCAcore:

4.2 Basic Rules

4.2.1 Abandoned Observable

The Abandoned observable is a basic observable which generates an event when an object has been either; left within a defined zone or when an object is removed from a defined zone. Please use the method mentioned earlier to add this element. A sample Abandoned observable is shown below:

{
    "typename": "vca.observable.Abandoned",
    "channel": 0,
    "zone": 3,
    "name": "Abandoned 5",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.2 Absence Observable

The Absence observable is a basic observable which generates an event when a zone does not have a object, of the specified class, present for the defined duration. Please use the method mentioned earlier to add this element. A sample Abandoned observable is shown below:

{
    "typename": "vca.observable.Absence",
    "channel": 0,
    "zone": 0,
    "duration": 1000,
    "filters": [],
    "confidence_threshold": 0.699999988079071,
    "name": "Absence 2",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.3 Aggressive Behaviour Observable (Fight)

The Aggressive Behaviour observable is a basic observable, which generates an event when a fight is detected in the field of view for longer than the specified duration.

Please use the method mentioned earlier to add this element. A sample Aggressive Behaviour observable is shown below:

{
    "typename": "vca.observable.AggressiveBehaviour",
    "channel": 0,
    "duration": 3000,
    "threshold": 0.95,
    "continuous_threshold": 0.5,
    "name": "Fight",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.4 Appear Observable

The Appear observable is a basic observable which generates an event when an object starts being tracked within a zone, e.g. a person who appears in the scene from a doorway. Please use the method mentioned earlier to add this element. A sample Appear observable is shown below:

{
    "typename": "vca.observable.Appear",
    "channel": 0,
    "zone": 3,
    "name": "Appear 5",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.5 Direction Observable

The Direction observable is a basic observable which generates an event when an object is moving in a specific direction. Please use the method mentioned earlier to add this element. A sample Direction observable is shown below:

{
    "typename": "vca.observable.Direction",
    "channel": 0,
    "angle": 77,
    "anglethreshold": 51,
    "zone": 0,
    "name": "Direction 3",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.6 Directional Crossing Observable

The Directional Crossing observable is a basic observable which generates an event when an object enters and exits a zone in a specific direction. Please use the method mentioned earlier to add this element. A sample Directional Crossing observable is shown below:

{
    "typename": "vca.observable.DirectionalCrossing",
    "channel": 0,
    "angle": 77,
    "anglethreshold": 51,
    "zone": 0,
    "filters": [
        "Vehicle"
        ],
    "confidence_threshold": 0.70,
    "name": "Directional Crossing 3",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.7 Disappear Observable

The Disappear observable is a basic observable which generates an event when an object stops being tracked within a zone, e.g. a person who exits the scene through a doorway. Please use the method mentioned earlier to add this element. A sample Disappear observable is shown below:

{
    "typename": "vca.observable.Disappear",
    "channel": 0,
    "zone": 3,
    "name": "Disappear 5",
    "triggers_action": true

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.8 Dwell Observable

The Dwell observable is a basic observable which generates an event when an object remains in a zone for a set interval. Please use the method mentioned earlier to add this element. A sample Dwell observable is shown below:

{
    "typename": "vca.observable.Dwell",
    "channel": 0,
    "zone": 0,
    "interval": 10000,
    "name": "Dwell 3",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.9 Enter Observable

The Enter observable is a basic observable which generates an event when an object enter a zone, e.g. when an object crosses from the outside of a zone to the inside of a zone. Please use the method mentioned earlier to add this element. A sample Enter observable is shown below:

{
    "typename": "vca.observable.Enter",
    "channel": 0,
    "zone": 3,
    "name": "Enter 5",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.10 Exit Observable

The Exit observable is a basic observable which generates an event when an object leaves a zone, e.g. when an object crosses from the inside of a zone to the outside of a zone. Please use the method mentioned earlier to add this element. A sample Exit observable is shown below:

{
    "typename": "vca.observable.Exit",
    "channel": 0,
    "zone": 3,
    "name": "Exit 5",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.11 Fall Observable

The Fall observable is a basic observable which generates an event when an object, detected as Person by the DL People Tracker, Deep Learning Skeleton Tracker or Deep Learning Object Tracker, is detected as fallen. Please use the method mentioned earlier to add this element. A sample Fall observable is shown below:

{
    "typename": "vca.observable.Fall",
    "channel": 0,
    "zone": 3,
    "duration": 1000,
    "confidence_threshold": 0,
    "name": "Fall 5",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.12 Hands Up Observable

The Hands Up observable is a basic observable which generates an event when an object, detected as Person by the DL Skeleton Tracker, is detected as having their hands up. Please use the method mentioned earlier to add this element. A sample Hands Up observable is shown below:

{
    "typename": "vca.observable.HandsUp",
    "channel": 0,
    "zone": 3,
    "duration": 1000,
    "confidence_threshold": 0.4,
    "name": "Hands Up 5",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.13 Line Counter Observable

The Line Counter observable is a basic observable which generates an event when an object is detected crossing a line. The referenced zone must be configured as a line, not a polygon.

Please use the method mentioned earlier to add this element. A sample Line Counter observable is shown below:

{
    "typename": "vca.observable.Line_Counter",
    "channel": 0,
    "direction": "both",
    "zone": 5,
    "calibration_width": 0,
    "filter_shadows": false,
    "name": "Line Counter 10",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.14 Loss of Signal Observable

This observable generates events when a stream is interrupted. Please use the method mentioned earlier to add this element. A sample Loss-of-signal observable is shown below:

{
    "typename": "vca.observable.LossOfSignal",
    "heartbeat_frequency": 1000,
    "channel": 0,
    "name": " - Loss of Signal",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.15 Occupancy Observable

The Occupancy observable generates an event when the number of objects of the defined filter changes in the specified zone. The threshold_operator, combined with threshold_value, can be used to control when the occupancy observable generates events in relation to the number of objects in the zone. Please use the method mentioned earlier to add this element.

The current count of this observable is available using the counter token or as Counter Value metadata, available in the metadata streams and as part of the event.

A sample Occupancy observable is shown below:

{
    "typename": "vca.observable.Occupancy",
    "channel": 0,
    "zone": 0,
    "x": 30708,
    "y": 3802,
    "filters": [
        "car",
        "truck",
        "van",
        "motorcycle",
        "bus"
    ],
    "confidence_threshold": 0.699999988079071,
    "threshold_value": 5,
    "threshold_operator": ">",
    "name": "Crossing Occupancy",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.16 Presence Observable

The Presence observable is a basic observable which generates an event when an object is present inside a zone. Please use the method mentioned earlier to add this element. A sample Presence observable is shown below:

{
    "typename": "vca.observable.Presence",
    "channel": 0,
    "zone": 4294967295,
    "name": "Presence 5",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.17 Stopped Observable

The Stopped observable is a basic observable which generates an event when an object is stationary inside a zone, for longer than the specified amount of time. Please use the method mentioned earlier to add this element. A sample Stopped observable is shown below:

{
    "typename": "vca.observable.Stopped",
    "zone": 4,
    "duration": 10000,
    "channel": 0,
    "name": "Stopped 3",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.18 Tailgating Observable

The Tailgating observable is a basic observable which generates an event when an object crosses through a zone, or over a line, within a set duration of one another. Please use the method mentioned earlier to add this element. A sample Tailgating observable is shown below:

{
    "typename": "vca.observable.Tailgating",
    "channel": 0,
    "zone": 0,
    "duration": 2000,
    "name": "Tailgating 3",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.2.19 Unattended Observable

The Unattended observable is a basic observable which generates an event when an object, with a specified class, is present in the attendee_zone but an object, of the specified class, is not present in the attendant_zone. Please note if filter is an empty array, the rule will never trigger.

Please use the method mentioned earlier to add this element. A sample Unattended observable is shown below:

{
    "typename": "vca.observable.Unattended",
    "channel": 0,
    "attendee_zone": 0,
    "attendant_zone": 1,
    "duration": 5000,
    "filters": [
        "person"
        ],
    "confidence_threshold": 0.699999988079071,
    "name": "Unattended 5",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.3 Filters

4.3.1 Accessory Filter

The Accessory Filter observable is a filter which generates an event when the object’s metadata, which has triggered the input observable, contains matching accessory data to the observables filter.

Due to the use cases associated with accessory detection, a differentiation can be made between a person with the detected accessory, a person classified as not wearing the accessory, and a person who has not yet been evaluated.

The Accessory Filter will only generate an event when all of the following requirements are met:

• The accessory filter entry matches an evaluated accessory on the object.
• The confidence_threshold is equal or greater than confidence of the detected accessory.
• The state matches the detection state of the accessory.

The algorithms that produce Accessory metadata require the Deep Learning Skeleton Tracker to work, if this tracker is not configured on the channel, accessory metadata will never be generated.

Please use the method mentioned earlier to add this element. A sample Object Filter observable is shown below:

{
    "typename": "vca.observable.AccessoryFilter",
    "channel": 0,
    "input": 1,
    "filter": "high_vis_vest",
    "confidence_threshold": 0.6000000238418579,
    "state": "present",
    "name": "Accessory Filter 3",
    "triggers_action": true
}

4.3.2 Colour Filter Observable

The Colour Filter observable is a filter which generates an event when the object, which has triggered the input observable, has 5% or more of any colour defined under filters. For this observable to generate an event, the channel must have the colour signature algorithm enabled. Please use the method mentioned earlier to add this element. A sample Colour Filter observable is shown below with all ten possible colours defined under filters:

{
    "typename": "vca.observable.ColourFilter",
    "channel": 0,
    "input": 6,
    "filters": [
        "Black",
        "Grey",
        "Blue",
        "Brown",
        "Cyan",
        "Green",
        "Red",
        "Magenta",
        "White",
        "Yellow"
    ],
    "name": "Colour Filter 13",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.3.3 Object Filter Observable

The Object Filter observable is a filter which generates an event when the object’s metadata, which has triggered the input observable, contains one of the classes in the filters array. A class must match either:

• One of the channel classification entries for calibration based classification.
• One of the confidence classification classes for the configured tracker.

An object’s metadata will only contain this data if the selected tracker is able, or configured, to add this metadata to the object. For example, if the filter car is added, this is possible in two ways:

• The channel is using the Deep Learning Object Tracker to detect that object class.
• The channel has been calibrated.

Please use the method mentioned earlier to add this element. A sample Object Filter observable is shown below:

{
    "typename": "vca.observable.ObjectFilter",
    "channel": 0,
    "input": 8,
    "filters": [
        "person",
        "vehicle"
    ],
    "confidence_threshold": 0.699999988079071,
    "name": "Object Filter 12",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.3.4 Retrigger Filter Observable

The Retrigger observable is a filter observable which generates an event when the input observable fires, as long as the input observable has not fired within the previous interval period. Please use the method mentioned earlier to add this element. A sample Retrigger Filter observable is shown below:

{
  "typename": "vca.observable.Retrigger",
  "channel": 0,
  "interval": 3000,
  "input": 1,
  "name": "Retrigger 1",
  "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.3.5 Speed Filter Observable

The Speed Filter observable is a filter which generates an event when the object, which has triggered the input observable, is travelling between a min and max speed. For this observable to generate an event, the channel must have been calibrated. Please use the method mentioned earlier to add this element. A sample Speed Filter observable is shown below:

{
    "typename": "vca.observable.Speed",
    "channel": 0,
    "input": 8,
    "minspeed": 3,
    "maxspeed": 10,
    "name": "Speed Filter 11",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.3.6 Source Filter Observable

The Source Filter observable is a filter which generates an event when the input observable triggers an event, and the source observable is in an on state. Valid inputs for use as a source are either the Schedule or HTTP other source observables. Please use the method mentioned earlier to add this element. A sample Source Filter observable is shown below:

{
    "typename": "vca.observable.SourceFilter",
    "channel": 0,
    "input": 5,
    "source": 7,
    "name": "Source Filter",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.4 Conditional Rules

4.4.1 And Observable

The And observable is a representation of the logical AND operation. Please use the method mentioned earlier to add this element. A sample And observable is shown below:

{
    "typename": "vca.observable.And",
    "channel": 0,
    "inputa": 4,
    "inputb": 5,
    "constrain_target": true,
    "name": "And 2",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General concepts section on Observables.

4.4.2 Continuously Observable

The Continuously observable generates an event when another event has been occurring continuously for a certain amount of time. The time parameter is user-specified. Please use the method mentioned earlier to add this element. A sample Continuously observable is shown below:

{
    "typename": "vca.observable.Continuously",
    "interval": 1000,
    "channel": 0,
    "input": 6,
    "constrain_target": true,
    "name": "Continuously 3",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.4.3 Counter Observable

The Counter observable generates an event when the value of count changes. The count value is defined by the input observables which either increment, decrement, or define its occupancy. A count value can be reset to 0 by defining input observable(s). When the input observable(s) trigger the count is reset. The threshold_operator, combines with threshold_value, can be used to control when the counter observable generates events in relation to the current count. The reset_inputs, specify observable(s) which, when triggered, will reset the count value to 0. Please use the method mentioned earlier to add this element. A sample Counter observable is shown below:

{
    "typename": "vca.observable.Counter",
    "channel": 0,
    "count": -20,
    "x": 32767,
    "y": 32767,
    "increment_inputs": [
        2,
        6
    ],
    "decrement_inputs": [
        7
    ],
    "occupancy_inputs": [
        8
    ],
    "reset_inputs": [ ],
    "threshold_value": 20,
    "threshold_operator": ">=",
    "name": "Counter 17",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.4.4 Not Observable

The Not observable is a representation of the logical NOT operation. Please use the method mentioned earlier to add this element. A sample Not observable is shown below:

{
    "typename": "vca.observable.Not",
    "channel": 0,
    "input": 7,
    "name": "Not",
    "constrain_target": false,
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.4.5 Or Observable

The Or observable is a representation of the logical OR operation. Please use the method mentioned earlier to add this element. A sample Or observable is shown below:

{
    "typename": "vca.observable.Or",
    "channel": 0,
    "inputa": 2,
    "inputb": 7,
    "constrain_target": true,
    "name": "Or 4",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.4.6 Previous Observable

The Previous observable generates an event when another event has occurred previously, within a certain amount of time. The time parameter is user-specified. Please use the method mentioned earlier to add this element. A sample Previous observable is shown below:

{
    "typename": "vca.observable.Previous",
    "interval": 1000,
    "channel": 0,
    "input": 5,
    "constrain_target": true,
    "name": "Previous 6",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.4.7 Repeatedly Observable

The Repeatedly observable generates an event when the input rule is triggered a set number of times within a defined period. The duration period is a window of time computed from every input event. Please use the method mentioned earlier to add this element. A sample Repeatedly observable is shown below:

{
    "typename": "vca.observable.Repeatedly",
    "input": 5,
    "duration": 1000,
    "occurrences": 3,
    "channel": 0,
    "constrain_target": true,
    "name": "Repeatedly 6",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.5 Other Sources

4.5.1 Armed

The Armed observable is a channel-independent observable which generates an event when the VCAcore system is Armed. Please use the method mentioned earlier to add this element. A sample Armed observable is shown below:

{
    "typename": "vca.observable.Armed",
    "name": "Armed Source",
    "triggers_action": true
}

The Armed observable does not have any specific properties. For a list of properties common to all observables, please see the General Concepts section on Observables.

4.5.2 Disarmed

The Disarmed observable is a channel-independent observable which generates an event when the VCAcore system is Disarmed. Please use the method mentioned earlier to add this element. A sample Disarmed observable is shown below:

{
    "typename": "vca.observable.Disarmed",
    "name": "Disarmed Source",
    "triggers_action": true
}

The Disarmed observable does not have any specific properties. For a list of properties common to all observables, please see the General Concepts section on Observables.

4.5.3 HTTP

The HTTP observable is a channel-independent observable which generates an event each time the state is changed to true. Please use the method mentioned earlier to add this element. A sample HTTP observable is shown below:

{
    "typename": "vca.observable.Http",
    "state": true,
    "name": "Http Source",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.5.4 Interval

The Interval observable is a channel-independent observable which generates an event each time the interval period passes. Please use the method mentioned earlier to add this element. A sample Interval observable is shown below:

{
    "typename": "vca.observable.Interval",
    "interval": 1000,
    "name": "Interval Source",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.5.5 Schedule

The Schedule observable is a channel-independent observable, which generates an event when the system clock coincides with a scheduled on period. Events are generated once per on period (if VCAcore is started during an on period a single event is fired). When set_arm_disarm is true, VCAcore will be armed and disarmed according to the defined periods of on / off. Please use the method mentioned earlier to add this element. A sample Schedule observable is shown below:

{
    "typename": "vca.observable.Schedule",
    "schedule": [
        "000000000000000000000000000000000000000000000000",
        "000000000000000000000000000000000000000000000000",
        "000000000000000111111111110000000000000000000000",
        "000000000000000000001111111111111000000000000000",
        "000011111111111111111100000000000000000000000000",
        "000000000000000000000000000000000000000000000000",
        "000000000000000000000000000000000000000000000000"
    ],
    "set_arm_disarm": false,
    "name": "Schedule Source",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.5.6 System

The System observable is a channel-independent observable, which generates an event when the specified resource_type passes a set threshold. Events will continue to send whilst the set threshold is met each time the min_interval duration has passed, if repeat_events is true. Please use the method mentioned earlier to add this element. A sample System observable is shown below:

{
    "typename": "vca.observable.System",
    "resource_type": "Gpu Utilisation",
    "threshold": 0,
    "min_interval": 60000,
    "repeat_events": true,
    "name": "System Alarm Source",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

4.5.7 License

The License observable is a channel-independent observable which generates events in the following cases:

• When an evaluation license has less than one week remaining.
• VCAserver’s connection to a License Server has been established.
• VCAserver’s connection to a License Server has been lost.

If repeat_events is false, a single event will be sent for each license event. (e.g. the license server is detected as disconnected when previously it was connected). If repeat_events is true, events will continue to be sent each time the min_interval duration has passed. Please use the method mentioned earlier to add this element. A sample License observable is shown below:

{
    "typename": "vca.observable.License",
    "min_interval": 60000,
    "repeat_events": true,
    "name": "License Server Changed Source",
    "triggers_action": true
}

In addition to the common properties described above, below is a list of properties specific to this observable:

For a list of properties common to all observables, please see the General Concepts section on Observables.

5 REST API Zones, Actions and VCAcore Status

5.1 Zones

5.1.1 Adding a Zone

To add a zone, send a POST request to the /api/zones endpoint. Unlike other elements, a zone does not have a typename property, so a zone may be added by sending a single POST request to the endpoint mentioned above with the correct payload. A sample zone is given below:

{
    "name": "Zone 0",
    "channel": 4,
    "points": [
        {
            "x": 20585,
            "y": 17374
        },
        {
            "x": 23368,
            "y": 51893
        }
    ],
    "colour": {
        "r": 252,
        "g": 175,
        "b": 62,
        "a": 1
    },
    "polygon": false,
    "detection": true
}

The properties of a zone object are given below:

5.2 Actions

Actions are objects that represent an operation that can be performed by the application. Actions can be linked to observables so that when an observable fires an event, the event causes the action to be triggered.

5.2.1 General Concepts

Actions can be added by sending a POST request to the /api/actions endpoint. Please use the method mentioned earlier to add this element. A sample TCP action is shown below:

{
    "typename": "vca.action.Tcp",
    "uri": "192.168.5.3",
    "port": 0,
    "body": "{ \"event_name\": \"{{name}}\", \"event_id\": {{id}} } ",
    "name": "TcpActionAddTest",
    "observables": [
        5,
        4
    ],
    "always_trigger": false
}

The following is a list of the properties common to all actions:

What follows is a list of all actions supported in VCAcore.

5.2.2 TCP Action

A TCP action sends data to a user-specified endpoint. Please use the method mentioned earlier to add this element. A sample TCP action is shown below:

{
    "typename": "vca.action.Tcp",
    "uri": "192.168.5.3",
    "port": 0,
    "body": "{ \"event_name\": \"{{name}}\", \"event_id\": {{id}} } ",
    "name": "TcpActionAddTest",
    "observables": [],
    "always_trigger": false
}

The following is a list of properties specific to the TCP action:

The TCP Body supports escape characters, allowing for inputs such NULL terminated strings (\x00). In turn these escape characters can be escaped through the use of an additional \ e.g. (\\x00).

For a list of properties common to all actions, please refer to the General Concepts section on actions.

5.2.3 HTTP Action

An HTTP action sends an HTTP(s) request to a user-specified endpoint according to the HTTP/1.1 standard. Please use the method mentioned earlier to add this element. A sample HTTP action is shown below:

{
    "typename": "vca.action.Http",
    "method": "GET",
    "uri": "http://192.168.1.60",
    "port": 0,
    "headers": "Content-Type: application/json",
    "body": "{ \"event_name\": \"{{name}}\", \"event_id\": {{id}} } ",
    "authentication": false,
    "username": "",
    "password": "",
    "send_snapshot": false,
    "pre_snapshots": 1,
    "post_snapshots": 1,
    "jpeg_quality": "average",
    "interval": 10,
    "multipart_name": "vca",
    "multipart_image_name": "vca",
    "verify_host_certificate": true,
    "ssl_method": "sslv3",
    "name": "",
    "observables": [],
    "always_trigger": false
}

The following is a list of properties specific to the HTTP action:

Please note multipart_name will need to be reflected in any scripts that handle this request, for example in php; this would be by using $_FILES['vca'] where vca is the string set in the multipart_name field

For a list of properties common to all actions, please refer to the General Concepts section on actions.

5.2.4 Email Action

An Email action sends an email in a user-specified format. Please use the method mentioned earlier to add this element. A sample Email action is shown below:

{
    "typename": "vca.action.Email",
    "server": "",
    "port": 0,
    "encryption": "none",
    "username": "",
    "password": "",
    "enable_authentication": false,
    "verify_host_certificate": false,
    "to": "",
    "cc": "",
    "bcc": "",
    "from": "",
    "subject": "{{type.string}} Cam ID {{#Channel}}{{id}}{{/Channel}}",
    "format": "custom",
    "body": "{{name}} triggered with at {{start.iso8601}}",
    "send_snapshot": false,
    "pre_snapshots": 0,
    "post_snapshots": 0,
    "jpeg_quality": "average",
    "interval": 0,
    "name": "",
    "observables": [],
    "always_trigger": false
}