Introduction
Example connection that subscribes to the tracking/state topic:
const WebSocket = require("ws");
const connection = new WebSocket("ws://127.0.0.1/bridge_external");
connection.on("open", () => {
connection.send(
JSON.stringify({
op: "subscribe",
topic: "/api/v1/tracking/state",
})
);
});
connection.on("message", (data) => {
const message = JSON.parse(data);
const isTracking = message.msg.is_tracking;
console.log(`The system is ${isTracking ? "" : "not "}tracking`);
});
import asyncio
import websockets
import json
async def subscribe_to_tracking():
uri = "ws://127.0.0.1/bridge_external"
async with websockets.connect(uri) as websocket:
await websocket.send(json.dumps({
"op": "subscribe",
"topic": "/api/v1/tracking/state"
}))
while True:
message = json.loads(await websocket.recv())
is_tracking = message['msg']['is_tracking']
print(f'The system is {"" if is_tracking else "not "}tracking')
asyncio.get_event_loop().run_until_complete(subscribe_to_tracking())
Welcome to the documentation of the Seervision Suite Production API. This documentation gives an overview of the communication mechanism between a client and the Seervision Suite (server).
Communication between the client and the server is works over WebSockets. The server accepts requests on port 80
on ws://127.0.0.1/bridge_external
.
If you are running multiple Seervision Suite instances on a single server (such as on an SVs4), the associated URLs change for the instances, i.e. ws://127.0.0.1/1/bridge_external
and ws://127.0.0.1/2/bridge_external
respectively.
The transport mechanism
Example message:
{
"op": "Example"
}
A message sent through the WebSocket is, in the base case, a JSON object with a string field called "op"
.
The op
field indicates the type of this message. Messages with different values for op
may be handled differently.
Optionally, a message can also provide an arbitrary string ID.
Example message with an ID:
{
"op": "Example",
"id": "example_id"
}
If an ID is provided with a message to the server, then related response messages will typically contain that ID as well. Log messages caused by this operation will also contain the ID.
Semantically, the ID is not an identifier of the specific message that it is in, but instead is an identifier for an interaction which may consist of a number of operations in back-and-forth messages. Thus, the ID may be used by multiple messages referring to the same transaction.
Authentication
An authentication mechanism is not provided for now, but might be added in the future.
Communication protocol
There are two concepts that allow the client communicate with the server, get updates and request changes.
Services and service calls
Example service call:
{
"op": "call_service",
"id": "take_control",
"service": "/api/v1/ptu_driver/take_control"
}
Example of a successful service response:
{
"op": "service_response",
"id": "take_control",
"service": "/api/v1/ptu_driver/take_control",
"result": true
"values": {
"success": true
}
}
Example of a failed service response:
{
"op": "service_response",
"id": "take_control",
"service": "/api/v1/ptu_driver/take_control",
"result": false,
"values": "Service does not exist"
}
A service provides a request/reply interface, which the client can utilize to request a one-time information or a simple "one-shot" action. To initiate the request, the client needs to send a message with a "call_service"
op
field. The server will then respond with a message containing a "service_response"
op
field, and additional information, specific to the service.
call_service
fields are:
Field | Required | Description |
---|---|---|
op |
yes | Must be the string "call_service" . |
service |
yes | A string defining the name of the service. See below for specific services provided by the API. |
id |
no | An optional string identifying the request. |
args |
no | An object with arguments for the request. This format of the object depends on the service . |
service_response
fields are:
Field | Required | Description |
---|---|---|
op |
yes | Will be the string "service_response" . |
service |
yes | The name of the service that was called. |
result |
yes | true if server managed to process request successfully, false otherwise. |
id |
no | If an ID was provided to the service request, then the service response will contain the ID. |
values |
no | If result is true , this field will contain an object with the result of the call, with the structure defined separately for every service. If result is false , values will be a string containing a detailed error message. |
Topics and topic subscriptions
Example "subscribe" message:
{
"op": "subscribe",
"topic": "/api/v1/tracking/state"
}
Example "unsubscribe" message:
{
"op": "unsubscribe",
"topic": "/api/v1/tracking/state"
}
Example topic message:
{
"op": "publish",
"topic": "/api/v1/tracking/state",
"msg": {
"data": false
}
}
A topic allows the client to subscribe to a stream of data from the server. This is especially useful when the client wants, for example, to get notified about the system status, e.g. tracking status. All messages in the topic are guaranteed to have the same format as specified below.
The client can send a message with an op
of "subscribe"
to subscribe to a specific topic and a message with op
equal to "unsubscribe"
to cancel the subscription. Once the subscription is initiated, the server will start sending messages of a type specific for this particular topic with "publish"
in the op
field.
subscribe
and unsubscribe
fields are specified as follows:
Field | Required | Description |
---|---|---|
op |
yes | Must be either "subscribe" or "unsubscribe" (string). |
topic |
yes | A string defining the name of the topic. See below for specific services provided by the API. |
id |
no | A string identifying the subscription. If it is not provided in the unsubscribe request, all subscriptions will be cancelled. If it is provided, only the subscription with the given id will be cancelled. |
publish
fields have the following specification:
Field | Required | Description |
---|---|---|
op |
yes | Must be the string "publish" . |
topic |
yes | A string defining the name of the topic. |
msg |
yes | An object containing the message payload. The structure of this field is specific to topics (see below). |
Versioning
The API version is defined by the v<major_version>.<minor_version>
string, where both major_version
and minor_version
are integers. All topics and services are versioned, and have a /api/v<major_version>/
prefix.
It is guaranteed that:
- The transport mechanism and communication protocols will not be changed in minor version updates.
- The general structure of messages described above will not change in minor version updates.
- The messages defined for every topic and every service will not have fields removed in minor version updates. Some fields may, however, be added.
Current version
The current version of the API is v1.11
.
Changelog
Date | Version | Description |
---|---|---|
Feb 28, 2024 | v1.11 | Add new tracking policies for container recall, modify tracking state messages, modify Start Tracking API |
Nov 15, 2023 | v1.10 | Deprecate TriggerZones API, release new Zones API, Automations API, VIP lost event |
Oct 20, 2023 | v1.9 | Allow recalling container with policy |
Feb 21, 2023 | v1.8 | Allow recalling container by name. |
Nov 30, 2022 | v1.7 | Deprecation of shot presets. |
Aug 26, 2021 | v1.6 | Presets are containers |
Jul 20, 2021 | v1.5 | Added tally status. |
Jun 30, 2021 | v1.4 | Added container status topic. |
Apr 30, 2021 | v1.3 | Added container groups. |
Apr 20, 2021 | v1.2 | Added containers, and added deprecation note to presets and shot presets. |
Mar 8, 2021 | v1.1 | Removed tracking and framing presets. |
Jun 23, 2020 | v1.0 | First public API release. |
Client libraries
If you would like to implement your own client application, here's a few links to get you started:
- NodeJS: ws.
- C++: boost.beast.
- Java: javax.websocket.
- Python: websockets.
Automations
The Seervision Suite provides two internal core automation features that trigger actions based on several events:
The fallback container component is designed to respond to VIP lost events. Upon such events, it automatically executes a predefined container, maintains a standstill position or zooms out. For more information, see our manual.
The Zone actions enable the execution of containers in response to specific Zone events. Such actions are defined by the user using the Seervision UI, and attached to specific Zones. For more information, see our manual.
By using the below automation endpoints, it is possible to enable or disable both of the aforementioned automations.
Service: enable/disable automations
Request message:
This service will enable or disable the internal automations described above.
Request to enable/disable the automations:
{
"op": "call_service",
"service": "/api/v1/automation/enabled/set",
"args": {
"data": true
}
}
The args
required have the following fields:
Field | Required | Description |
---|---|---|
data |
yes | A boolean set to true to enable the automations or false to disable them. |
Response message:
Response to the "enable/disable the automations" request:
{
"op": "service_response",
"service": "/api/v1/automation/enabled/set",
"result": true,
"values": {
"success": true
}
}
The values
returned will have the following fields:
Field | Required | Description |
---|---|---|
success |
yes | A boolean set to true if the requested operation is successful or false otherwise. |
Topic: get automations state
Message to initiate the subscription:
{
"op": "subscribe",
"topic": "/api/v1/automation/enabled"
}
Message to cancel the subscription:
{
"op": "unsubscribe",
"topic": "/api/v1/automation/enabled"
}
The /api/v1/automation/enabled
topic can be used to subscribe to changes to the automation state. It will publish a new message whenever the state is changed. Upon subscription, the client will receive one immediate message with the current automation state.
Example topic publication:
{
"op": "publish",
"topic": "/api/v1/automation/enabled",
"msg": {
"data": true
}
}
The fields of the messages in this topic are:
Field | Required | Description |
---|---|---|
data |
yes | A boolean set to true if the rautomations are enabled or false otherwise. |
Containers
The system is controllable through user-defined containers. Each container consists of versatile components, that define the behavior of the container once it is recalled. Among other things, containers allow the user to request the camera move to a specific preset (pan/tilt/zoom/focus) position, as well as define and recall presets of framing shots. For more information, see our manual.
This section defines services for creating, deleting, and recalling containers, as well as two topics that publish updates regarding containers.
Service: create a container
Request message:
This service will create a container using the current system state as specified by the provided configuration type.
Request to create a Position container:
{
"op": "call_service",
"service": "/api/v1/containers/create",
"args": {
"name": "New container",
"configuration_type": "position"
}
}
Request to create a Shot container:
{
"op": "call_service",
"service": "/api/v1/containers/create",
"args": {
"name": "",
"configuration_type": "shot"
}
}
Request to create an Empty container:
{
"op": "call_service",
"service": "/api/v1/containers/create",
"args": {
"name": "",
"configuration_type": "empty"
}
}
The args
field passed with the request can contain the following fields:
Field | Required | Description |
---|---|---|
name |
no | A string, the name of the container. If not provided or empty, will be generated automatically. |
configuration_type |
yes | Container configuration. The following configurations are supported:
|
Response message:
Response to the "create a container" request:
{
"op": "service_response",
"service": "/api/v1/containers/create",
"result": true,
"values": {
"new_container": {
"id": "6f0c84",
"name": "Container 1"
}
}
}
The values
returned will have the following fields:
Field | Required | Description |
---|---|---|
new_container |
yes | A Container object defining the newly created container. |
Service: delete a container
This service will delete a container with the provided ID. It will not throw if the container with the given ID is missing.
Request message:
Request to delete a container:
{
"op": "call_service",
"service": "/api/v1/containers/delete",
"args": {
"container_id": "6f0c84"
}
}
The args
passed with this call should have the following structure:
Field | Required | Description |
---|---|---|
container_id |
yes | A string identifying the container to be deleted. |
Response message:
Response to the "delete a container" request:
{
"op": "service_response",
"service": "/api/v1/containers/delete",
"result": true,
"values": {}
}
The server will return an empty message in response.
Service: get all containers
This service will return all saved containers.
Request message:
Request to get all containers:
{
"op": "call_service",
"service": "/api/v1/containers/get_all"
}
This service call doesn't expect any arguments.
Response message:
Response to the "get all containers" request:
{
"op": "service_response",
"service": "/api/v1/containers/get_all",
"result": true,
"values": {
"containers": [
{
"id": "f0c846",
"name": "Container 1"
},
{
"id": "a87c21",
"name": "Main stage"
}
]
}
}
The values
returned will have the following fields:
Field | Required | Description |
---|---|---|
containers |
yes | An array of Container elements. |
Service: recall a container
This service sends a request to the Seervision Suite to recall specific container using its name or ID.
Request message:
Request to recall a container:
{
"op": "call_service",
"service": "/api/v1/containers/recall",
"args": {
"container": "My container",
"policy": {}
}
}
The service expects the following args
structure:
Field | Required | Description |
---|---|---|
container |
yes | A string with the container's name or identifier. |
container_id DEPRECATED |
no | A string with the container's identifier. Starting v1.8 this field is no longer used and is only kept for backward compatibility reasons. |
policy |
no | A Policy structure that communicates to the tracking container which subject to track. If not provided, the system will start tracking either the previously tracked person, or, if the previously tracked person is no longer visible (or there was no last tracked person at all), the person closest to the middle of the frame. If the container does not have a tracking component, adding this argument causes a recall failure. This option is only available starting v1.9 . |
Response message:
Response to the "recall a container" request when container doesn't exist
{
"op": "service_response",
"service": "/api/v1/containers/recall",
"result": false,
"values": "Container with id \"756064\" does not exist"
}
Response to the successful "recall a container" request:
{
"op": "service_response",
"service": "/api/v1/containers/recall",
"result": true,
"values": {}
}
If successful, the response will be an empty message. In all other cases, the result
will be false
and the values
field will contain an error message. Those messages can include:
Container with name or ID <X> does not exist.
If the name or ID is incorrect.Container with name <X> exists multiple times.
If multiple containers have the name the recall requested.
Topic: get containers
Message to initiate the subscription:
{
"op": "subscribe",
"topic": "/api/v1/containers/updates"
}
Message to cancel the subscription:
{
"op": "unsubscribe",
"topic": "/api/v1/containers/updates"
}
The /api/v1/containers/updates
topic can be used to subscribe to changes to the containers. It will publish a new message whenever a container is added, deleted, or updated. Upon subscription, the client will receive one immediate message with the current containers.
Example topic publication:
{
"op": "publish",
"topic": "/api/v1/containers/updates",
"msg": {
"containers": [
{
"id": "f0c846",
"name": "Container 1"
},
{
"id": "a87c21",
"name": "Main stage"
}
]
}
}
The fields of the messages in this topic are:
Field | Required | Description |
---|---|---|
containers |
yes | An array of Container elements. |
Topic: get container status
Message to initiate the subscription:
{
"op": "subscribe",
"topic": "/api/v1/containers/status"
}
Message to cancel the subscription:
{
"op": "unsubscribe",
"topic": "/api/v1/containers/status"
}
The /api/v1/containers/status
topic can be used to subscribe to notifications about the recall status of containers. Since only one container at a time can be recalled, the message sent through this topic contains information only about the last recalled container.
Example topic publication:
{
"op": "publish",
"topic": "/api/v1/containers/status",
"msg": {
"container_id": "f0c846",
"status": "running",
"status_message": ""
}
}
The fields of the messages in this topic are:
Field | Required | Description |
---|---|---|
container_id |
yes | A string representing the unique container ID. |
status |
yes | A string representing the container status. There are four statuses that get reported by this topic:
|
status_message |
yes | A message containing more details regarding the status of the container. Usually is used for "raised_error" status indicating the reasons the container failed to be executed. See Start Tracking API for the possible error messages that may occur. |
The system guarantees that every running
status update is always followed by an abandoned
, completed
, interrupted
or raised_error
status update for the same container.
Container groups
In the UI of the Seervision Suite, Containers can be collected into groups for easier management when there are many containers in the interface. This API provides the means to query these groups.
Service: get container groups
Request message:
This service will return the list of container groups in the order they appear in the UI.
Request to get container groups:
{
"op": "call_service",
"service": "/api/v1/container_groups/get_all"
}
This service call doesn't expect any arguments.
Response message:
Response to the "get container groups" request:
{
"op": "service_response",
"service": "/api/v1/container_groups/get_all",
"result": true,
"values": {
"container_groups": [{
"group_id": "6f0c84",
"group_name": "Group 1",
"color": "flamingo",
"container_ids": ["52ac65", "c6fd11"]
}, {
"group_id": "7c0849",
"group_name": "Group 2",
"color": "roquefort",
"container_ids": []
}, {
"group_id": "",
"group_name": "",
"color": "",
"container_ids": ["995d22"]
}]
}
}
The values
returned will have the following fields:
Field | Required | Description |
---|---|---|
container_groups |
yes | An array of ContainerGroups. It is guaranteed that the groups appear in the same order as they are displayed in the UI. It is guaranteed that a default group will always be there, and that it will be the last in the list. |
Topic: get container groups
Message to initiate the subscription:
{
"op": "subscribe",
"topic": "/api/v1/container_groups/updates"
}
Message to cancel the subscription:
{
"op": "unsubscribe",
"topic": "/api/v1/container_groups/updates"
}
The /api/v1/container_groups/updates
topic can be used to subscribe to the changes to the container groups. It will publish a new message whenever a container group is added or deleted, or when the order of containers in one of the groups is updated. Upon subscription, the client will receive one immediate message with the current container groups.
Example topic publication:
{
"op": "publish",
"topic": "/api/v1/container_groups/updates",
"msg": {
"container_groups": [{
"group_id": "6f0c84",
"group_name": "Group 1",
"color": "flamingo",
"container_ids": ["52ac65", "c6fd11"]
}, {
"group_id": "7c0849",
"group_name": "Group 2",
"color": "roquefort",
"container_ids": []
}, {
"group_id": "",
"group_name": "",
"color": "",
"container_ids": ["995d22"]
}]
}
}
The fields of the messages in this topic are:
Field | Required | Description |
---|---|---|
container_groups |
yes | An array of ContainerGroups. It is guaranteed that the groups appear in the same order as they are displayed in the UI. It is guaranteed that a default group will always be there, and that it will be the last in the list. |
Zones
Zones can be defined through the Seervision Suite UI to enable zone-based workflow automations, both for visual and audio detections. Three types of Zones are currently supported by the Seervision Suite:
- Trigger Zones: These Zones are used to trigger specific events when people appear or disappear within them. Can be queried under the
/api/v1/trigger_zones
endpoint. - Exclusion Zones: These Zones are used to exclude persons from triggering automations. Can be queried under the
/api/v1/exclusion_zones
endpoint. - Tracking Zones: These Zones are used to specify a zone where detections are allowed, while detections outside of this zone are fully ignored. Can be queried under the
/api/v1/tracking_zones
endpoint.
This section describes a service and a topic that can be used to retrieve information about all available zones.
Service: set zone state
Request message:
This service changes the "enabled" state of the specified zones.
Example request to change status of zones:
{
"op": "call_service",
"service": "/api/v1/exclusion_zones/set_state",
"args": {
"zones": ["756064a6f0c84610b2e63fea54a87c21", "My Zone 1"],
"set_enable": true
}
}
The args
field passed with the request must have the following fields:
Field | Required | Description |
---|---|---|
zones |
yes | A list of strings (either their name or unique ID) to set the state |
set_enable |
yes | A boolean, true if the zone should be enabled, and false otherwise. |
Response message:
Example response to the "set zones state" request:
{
"op": "service_response",
"service": "/api/v1/exclusion_zones/set_state",
"result": true,
"values": {
"responses": [
{
"zone": "756064a6f0c84610b2e63fea54a87c21",
"success": true,
"message": ""
},
{
"zone": "My Zone 1",
"success": true,
"message": ""
}
]
}
}
The server response will contain an array of the same size as the request. The returned fields for each specified Zone will have the following structure:
Field | Required | Description |
---|---|---|
zone |
yes | A string containing the Zone ID or name of the relevant Zone |
success |
yes | A boolean indicating whether the request was succesful or not. |
message |
yes | A string containing an error message if the request failed, such as Zone not found , when the Zone ID or name is incorrect. |
Topic: get zones state
Message to initiate the subscription:
{
"op": "subscribe",
"topic": "/api/v1/<zones_type>/state"
}
Message to cancel the subscription:
{
"op": "unsubscribe",
"topic": "/api/v1/<zones_type>/state"
}
The /api/v1/<zones_type>/state
topic can be used to subscribe to changes to the zones. It will publish a new message whenever a zone is added, deleted, renamed or the state is changed (i.e., enabled/disabled or the list of inside persons changed). Upon subscription, the client will receive one immediate message with the current zones and their state.
Example topic publication:
{
"op": "publish",
"topic": "/api/v1/exclusion_zones/state",
"msg": {
"zones": [ {
"zone": {
"name": "My zone",
"id": "756064a6f0c84610b2e63fea54a87c21",
"frame_id": "world",
"type": "audio_exclusion_zone"
}
"enabled": true
"inside": ["7", "23", "Foo", "4"]
}, {...}
]
}
}
The fields of the messages in this topic are:
Field | Required | Description |
---|---|---|
zones |
yes | An array of ZoneState elements. |
Events
The Events endpoint can be used by consumers to receive updates when the Seervision Suite detects a specific event. Currently, the following sources emit events:
- Zones
- Trigger Zones (deprecated since
v1.10
- Seervision Suitev73.0.0
in favor of Zones) - VIP lost
Topic: get events fired by Zones
Message to initiate the subscription:
{
"op": "subscribe",
"topic": "/api/v1/events/zones"
}
Message to cancel the subscription:
{
"op": "unsubscribe",
"topic": "/api/v1/events/zones"
}
The /api/v1/events/zones
can be used to get updates from the Seervision Suite when a specific event is fired by a Zone. As soon as a Zone detects an event, a message will be sent to this topic with event information.
When using the API, keep in mind that:
- The events only get sent for enabled Zones.
- The events get triggered with a time delay specified in the Zone through the UI.
- It is possible to get a list of events hapenning in multiple Zones at the same time, within a single message.
Example topic publication:
{
"op": "publish",
"topic": "/api/v1/events/zones",
"msg": {
"events": [ {
"event": "person_appeared",
"zone": {
"name": "My zone 1",
"id": "756064a6f0c84610b2e63fea54a87c21",
"frame_id": "",
"type": "vision_trigger_zone"
},
"caused_by": "15",
"inside": ["Foo", "10", "15"]
}, {...}]
}
}
The list of msg
will have the ZoneEvent type.
Topic: get events fired by trigger zones - DEPRECATED
Message to initiate the subscription:
{
"op": "subscribe",
"topic": "/api/v1/events/trigger_zones"
}
Message to cancel the subscription:
{
"op": "unsubscribe",
"topic": "/api/v1/events/trigger_zones"
}
The /api/v1/events/trigger_zones
can be used to get updates from the Seervision Suite when a specific event is fired by a trigger zone. As soon as a trigger zone detects an event, a message will be sent down this topic with event information.
When using the API, keep in mind that:
- The events only get sent for enabled trigger zones.
- The events get triggered with a delay (time threshold) specified in the zone through the UI.
- If an event is superseded by event triggered by another trigger zone with a higher priority, it will not be fired.
Example topic publication:
{
"op": "publish",
"topic": "/api/v1/events/trigger_zones",
"msg": {
"type": "person_entered",
"zone_id": "756064a6f0c84610b2e63fea54a87c21"
}
}
The msg
object will have the TriggerZoneEvent type.
Topic: get event fired by VIP status
Message to initiate the subscription:
{
"op": "subscribe",
"topic": "/api/v1/events/vip_lost"
}
Message to cancel the subscription:
{
"op": "unsubscribe",
"topic": "/api/v1/events/vip_lost"
}
The Seervision Suite can also emit events when the VIP (tracked person) is no longer detectable in the video feed. This information is available through the /api/v1/events/vip_lost
endpoint.
When using the API, keep in mind:
- The Suite employs advanced logic to determine the VIP’s visibility. It ensures that temporary occlusions do not trigger false alerts, maintaining high accuracy in event detection.
- The event is reliably emitted only under certain conditions to avoid false alarms. These conditions are finely tuned to discern between temporary and significant loss of VIP visibility.
Example topic publication:
{
"op": "publish",
"topic": "/api/v1/events/vip_lost",
"msg": {
"seq": 0,
"stamp": {
"secs": 1694342678,
"nsecs": 124843120
},
"frame_id": ""
}
}
The fields of the messages in this topic are:
Field | Required | Description |
---|---|---|
seq |
yes | An integer containing the sequence number of the message. |
stamp |
yes | A structure containing the unix epoch time in precision of seconds (secs ) and nanoseconds (nsecs ) the event is fired. |
frame_id |
yes | A string containing the video stream reference frame ID at the time the VIP was lost. Currently, it is always empty. |
PTU control
Some PTUs/PTZs (e.g. from Panasonic) have their own control system for the PTU (Pan Tilt Unit). The Seervision API provides a set of services that allow the client take control of the head, release control, as well as a topic that publishes messages which help the client determine whether Seervision Suite is currently in control. When the Seervision Suite releases control, it stops sending any control message to the PTU.
Service: take control
Request message:
Request to take control:
{
"op": "call_service",
"service": "/api/v1/ptu_driver/take_control"
}
This service call doesn't expect any arguments.
Response message:
Response to the "take control" request:
{
"op": "service_response",
"service": "/api/v1/ptu_driver/take_control",
"result": true,
"values": {}
}
The server will return an empty message in response.
Service: release control
Request to release control
{
"op": "call_service",
"service": "/api/v1/ptu_driver/release_control"
}
This service call doesn't expect any arguments.
Response message:
Response to the "release control" request:
{
"op": "service_response",
"service": "/api/v1/ptu_driver/release_control",
"result": true,
"values": {}
}
The server will return an empty message in response.
Topic: PTU driver control status
Message to initiate the subscription:
{
"op": "subscribe",
"topic": "/api/v1/ptu_driver/in_control"
}
Message to cancel the subscription:
{
"op": "unsubscribe",
"topic": "/api/v1/ptu_driver/in_control"
}
A client can subscribe to changes to the control status from the /api/v1/ptu_driver/in_control
topic. Upon subscription, the client will receive one immediate message with the current status.
Example topic publication:
{
"op": "publish",
"topic": "/api/v1/ptu_driver/in_control",
"msg": {
"in_control": false
}
}
The messages sent through this topic will have the following fields:
Field | Required | Description |
---|---|---|
in_control |
yes | true means that Seervision Suite is in control, and false stands for the opposite. |
Tracking state
This section defines services and topics related to the tracking state of the system, i.e. whether the system is currently tracking someone or not.
Service: start tracking
Request message:
Request to start tracking:
{
"op": "call_service",
"service": "/api/v1/tracking/start",
"args": {
"policy": {}
}
}
Field | Required | Description |
---|---|---|
policy |
no | A Policy structure that communicates to the tracking container which subject to track. If not provided, the system will start tracking either the previously tracked person, or, if the previously tracked person is no longer visible (or there was no last tracked person at all), the person closest to the middle of the frame. |
Response message:
Response to the "start tracking" request:
{
"op": "service_response",
"service": "/api/v1/tracking/start",
"result": true,
"values": {}
}
If successful, the response will be an empty message. In all other cases, the result
will be false
and the values
field will contain an error message. Those messages can include:
General Errors:
-
No connection to the backend. Try again or relaunch the Suite.
If there is no connection or the connection with the system is lost. When this error occures, usually can be solved only be relaunching the Suite. No persons data available.
If there is no connection or the connection with the person tracker is lost. When this error occures, usually can be solved only be reboot the whole system.No visible persons to apply a shot to.
If the people in the stream are not visible or trackable."Failed to 'enable'/'disable' tracking within 'X' seconds."
If the tracking system is not responding.Invalid policy type, '*type*', expected one of the following: '["people", "location", "last_tracked_people"]' or empty.
If the policy type is invalid.
Policy people
Errors:
No person identifiers provided.
If the requested people list is empty.Group shot is not supported, yet. Only one person identifier is allowed.
If the requested people list contains more than one person identifer.Requested person(s) '["Aristotelis"]' are not currently visible or selectable to apply a shot to.
If the requested people list contains people that are not visible or inside an exclusion zone or outside of a tracking zone.
Policy location
Errors:
Invalid location type, '*location*' , expected one of the following: '["middle", "left", "right", "point"]' or empty.
If the location type is invalid.Invalid location point coordinates, '[*x*, *y*]', expected coordinates in (0, 1).
If the location point provided is outside of the valid region.
Policy last_tracked_people
Errors:
No last tracked person to select.
If the system does not have any last tracked person saved, maybe due to a VIP lost event.The last tracked persons, '["1"]', are not currently visible or selectable to apply a shot to.
If any of the last tracked people is not visible or inside an exclusion zone or outside of a tracking zone.
Service: stop tracking
Request to stop tracking
{
"op": "call_service",
"service": "/api/v1/tracking/stop"
}
Response message:
Response to the "stop tracking" request:
{
"op": "service_response",
"service": "/api/v1/tracking/stop",
"result": true,
"values": {}
}
If successful, the response will be an empty message. In all other cases, the result
will be false
and the values
field will contain an error message.
Topic: get tracking state
Message to initiate the subscription:
{
"op": "subscribe",
"topic": "/api/v1/tracking/state"
}
Message to cancel the subscription:
{
"op": "unsubscribe",
"topic": "/api/v1/tracking/state"
}
A client can subscribe to changes to the tracking state from the /api/v1/tracking/state
topic. Upon subscription, the client will receive one immediate message with the current state.
Example topic publication:
{
"op": "publish",
"topic": "/api/v1/tracking/state",
"msg": {
"is_tracking": false,
"people": ["1", "Aristotelis"]
}
}
The messages sent through this topic have the following structure:
Field | Required | Description |
---|---|---|
is_tracking |
yes | A boolean. true if the system is currently tracking a person, and false otherwise. |
people |
yes | An array of strings containing the identifiers of the current tracked people if tracking is on or the last people otherwise. |
Trigger zones - DEPRECATED
This section describes a service and a topic that can be used to retrieve information about the trigger zones defined in the Seervision Suite.
Service: set trigger zone state - DEPRECATED
Request message:
This service changes the "enabled" state of a single trigger zone.
Request to change status of a single trigger zone:
{
"op": "call_service",
"service": "/api/v1/trigger_zones/set_status_of_single_zone",
"args": {
"zone_id": "756064a6f0c84610b2e63fea54a87c21",
"is_enabled": true
}
}
The args
field passed with the request must have the following fields:
Field | Required | Description |
---|---|---|
zone_id |
yes | A string, unique ID of the trigger zone that initiated the event. |
is_enabled |
yes | A boolean, true if the zone should be enabled, and false otherwise. |
Response message:
Response to the "update trigger zone 'enabled' status" request:
{
"op": "service_response",
"service": "/api/v1/trigger_zones/set_status_of_single_zone",
"result": true,
"values": {}
}
The server will return an empty message in response if the zone was successfully updated.
Service: set state of all trigger zones - DEPRECATED
Request message:
This service changes the "enabled" state of a single trigger zone.
Request to change status of all trigger zones:
{
"op": "call_service",
"service": "/api/v1/trigger_zones/set_status_of_all_zones",
"args": {
"is_enabled": true
}
}
The args
field passed with the request must have the following fields:
Field | Required | Description |
---|---|---|
is_enabled |
yes | A boolean, true if all trigger zones should be enabled, and false otherwise. |
Response message:
Response to the "update trigger zones 'enabled' status" request:
{
"op": "service_response",
"service": "/api/v1/trigger_zones/set_status_of_all_zones",
"result": true,
"values": {}
}
The server will return an empty message in response if all zones got successfully updated.
Service: get trigger zones - DEPRECATED
Request message:
This service returns the list of trigger zones in the system.
Request to list trigger zones:
{
"op": "call_service",
"service": "/api/v1/trigger_zones/get_all"
}
This service call doesn't expect any arguments.
Response message:
Response to the "get all trigger zones" request:
{
"op": "service_response",
"service": "/api/v1/trigger_zones/get_all",
"result": true,
"values": {
"trigger_zones": [
{
"id": "756064a6f0c84610b2e63fea54a87c21",
"name": "Trigger Zone 1",
"is_enabled": false
},
{
"id": "856064a6f0c84610b2e63fea54a87c21",
"name": "Trigger Zone 2",
"is_enabled": true
}
]
}
}
The values
returned will have the following fields:
Field | Required | Description |
---|---|---|
trigger_zones |
yes | An array of TriggerZone elements. |
Topic: get trigger zones - DEPRECATED
Message to initiate the subscription:
{
"op": "subscribe",
"topic": "/api/v1/trigger_zones/updates"
}
Message to cancel the subscription:
{
"op": "unsubscribe",
"topic": "/api/v1/trigger_zones/updates"
}
The /api/v1/trigger_zones/updates
topic can be used to subscribe to changes to the trigger zones. It will publish a new message whenever a trigger zone is added, deleted, or renamed. Upon subscription, the client will receive one immediate message with the current trigger zones.
Example topic publication:
{
"op": "publish",
"topic": "/api/v1/trigger_zones/updates",
"msg": {
"trigger_zones": [
{
"id": "756064a6f0c84610b2e63fea54a87c21",
"name": "Trigger Zone 1",
"is_enabled": false
},
{
"id": "856064a6f0c84610b2e63fea54a87c21",
"name": "Trigger Zone 2",
"is_enabled": true
}
]
}
}
The fields of the messages in this topic are:
Field | Required | Description |
---|---|---|
trigger_zones |
yes | An array of TriggerZone elements. |
Endpoints
This section describes the services that allow the user to check availability of other services and topics, provided by the API.
Service: is service available
Request message:
This service accepts service string in a request, and returns true
if the service exists, and false
otherwise.
Request to check service availability
{
"op": "call_service",
"service": "/api/v1/endpoints/is_service_available",
"args": {
"service": "/api/v1/tracking/start"
}
}
The args
field passed with the request must have the following fields:
Field | Required | Description |
---|---|---|
service |
yes | A string, the service path to check. |
Response message:
Response to the "check service availability" request if service exists:
{
"op": "service_response",
"service": "/api/v1/endpoints/is_service_available",
"result": true,
"values": {
"is_available": true
}
}
Response to the "check service availability" request if service does not exist:
{
"op": "service_response",
"service": "/api/v1/endpoints/is_service_available",
"result": true,
"values": {
"is_available": false
}
}
The values
returned will have the following fields:
Field | Required | Description |
---|---|---|
is_available |
yes | A boolean, true if the service exists, false otherwise. |
Service: is topic available
Request message:
This service accepts topic string in a request, and returns true
if the topic exists, and false
otherwise.
Request to check topic availability
{
"op": "call_service",
"service": "/api/v1/endpoints/is_topic_available",
"args": {
"topic": "/api/v1/tracking/state"
}
}
The args
field passed with the request must have the following fields:
Field | Required | Description |
---|---|---|
topic |
yes | A string, the topic path to check. |
Response message:
Response to the "check topic availability" request if topic exists:
{
"op": "service_response",
"service": "/api/v1/endpoints/is_topic_available",
"result": true,
"values": {
"is_available": true
}
}
Response to the "check topic availability" request if topic does not exist:
{
"op": "service_response",
"service": "/api/v1/endpoints/is_topic_available",
"result": true,
"values": {
"is_available": false
}
}
The values
returned will have the following fields:
Field | Required | Description |
---|---|---|
is_available |
yes | A boolean, true if the topic exists, false otherwise. |
Common object definitions
This section contains definitions of messages used in topic publications and service responses. Every message is an object with one or more strongly typed fields.
Container
Example of a Container message:
{
"id": "4a6f0c",
"name": "Container 1"
}
This object contains information about a container.
Field | Required | Description |
---|---|---|
id |
yes | A string representing the unique container ID. |
name |
yes | A string, the name of the container. |
ContainerGroup
Example of a ContainerGroup message for a user-defined group:
{
"group_id": "7c0849",
"group_name": "Group 2",
"color": "roquefort",
"container_ids": ["995d22"]
}
Example of a ContainerGroup message for a default group:
{
"group_id": "",
"group_name": "",
"color": "",
"container_ids": ["52ac65"]
}
This object contains information about a container group. The message content differs based on whether it is a user-defined group, or a default group. All containers that appear in the UI as ungrouped belong to the default group.
Field | Required | Description |
---|---|---|
group_id |
yes | A string representing the unique group ID, or an empty string if it is a default group. |
group_name |
yes | A string, the name of the group. This string will be empty for the default group. |
color |
yes | A string defining group color. This string will be empty for the default group, or one of the predefined set of strings for a user-defined group. |
container_ids |
yes | An array of unique Container IDs belonging to this group. It is guaranteed that the order of the IDs matches the order in which the containers are displayed in the UI. |
Point2d
Example of a Point2d message:
{
"x": 0.5,
"y": 0.5
}
This message is used to describe a point position in 2-dimensional coordinates.
Field | Required | Description |
---|---|---|
x |
yes | A 32-bit IEEE float number, x coordinate. |
y |
yes | A 32-bit IEEE float number, y coordinate. |
Policy
Example of a Policy message:
{
"type": "people",
"people": ["Aristotle"]
}
This object contains information about tracking targets.
Field | Required | Description |
---|---|---|
type |
yes | A string describing the policy type. The supported policy types are people : Select the people to make a static or tracking shot by providing their identifiers.location : Select the persons to track closest to the point the location argument specifies.last_tracked_people : Select the last tracked people or currently being tracked. |
people |
yes, if type is people |
An array of strings defining the people to make a static or tracking shot. Currently, only a single person is allowed. The string can be either of the following:
|
location |
yes, if type is location |
If the location type is selected, then the system will start tracking the person closest to the specified location.
|
location_point |
yes, if type is location and location is point |
This field must be a Point2d identifying a location in the field of view. Both x and y values must be numbers between 0.1 and 0.99 , inclusive. x identifies the horizontal position, and y identifies the vertical one. For example:
|
TriggerZone - DEPRECATED
Example of a TriggerZone message:
{
"id": "756064a6f0c84610b2e63fea54a87c21",
"name": "Trigger Zone 1",
"is_enabled": false
}
This message is used to describe a trigger zone.
Field | Required | Description |
---|---|---|
id |
yes | A string, unique ID of the trigger zone. |
name |
yes | A string with the trigger zone name. |
is_enabled |
yes | A boolean indicating whether the zone is enabled or not. When the zone is not enabled, it does not trigger any events. |
TriggerZoneEvent - DEPRECATED
Example of a TriggerZoneEvent message with "person_entered" type:
{
"zone_id": "756064a6f0c84610b2e63fea54a87c21",
"type": "person_entered"
}
This message is used to describe an event triggered by a trigger zone.
Field | Required | Description |
---|---|---|
zone_id |
yes | A string, unique ID of the trigger zone that initiated the event. |
type |
yes | A string identifying event type. Possible values are:
|
person_id |
yes | A string identifying the person triggering the event. |
ZoneHeader
Example of a ZoneHeader message:
{
"name": "My zone 1",
"id": "756064a6f0c84610b2e63fea54a87c21",
"frame_id": "",
"type": "vision_trigger_zone"
}
This object contains the core data needed to specify a Zone.
Field | Required | Description |
---|---|---|
name |
yes | A string containing the user-defined name of the Zone. |
id |
yes | A string containing the unique ID of the Zone. |
frame_id |
yes | A string identifying the frame of reference of the Zone. It is currently only in use for audio zones. |
type |
yes | A string identifying the Zone type. Possible values are:
|
ZoneEvent
Example of a ZoneEvent message with "person_appeared" event:
{
"event": "person_appeared",
"zone": {
"name": "My zone 1",
"id": "756064a6f0c84610b2e63fea54a87c21",
"frame_id": "",
"type": "vision_trigger_zone"
},
"caused_by": "15",
"inside": ["Foo", "10", "15"]
}
This message is used to describe an event fired by a Zone.
Field | Required | Description |
---|---|---|
event |
yes | A string identifying the event type. Possible values are:
|
zone |
yes | A ZoneHeader object identifying the zone which emitted the event. |
caused_by |
yes | A string with the person ID or name triggering the event. |
inside |
yes | A list of strings specifying the person IDs or names that are currently inside the Zone which triggered the event. |
ZoneState
Example of a ZoneState message:
{
"zone": {
"name": "My zone 1",
"id": "756064a6f0c84610b2e63fea54a87c21",
"frame_id": "",
"type": "vision_trigger_zone"
},
"enabled": true,
"inside": ["Foo", "10", "15"]
}
This message is used to describe a Zone state.
Field | Required | Description |
---|---|---|
zone |
yes | A ZoneHeader object identifying the Zone which emitted the the event. |
enabled |
yes | A boolean indicating whether the Zone is enabled or not. |
inside |
yes | A list of strings specifying the person IDs or names that are currently inside the Zone. |