CamOverlay App 3.x and 4.x API documentation – CamStreamer Support

CamOverlay App is an application running inside the camera on an Axis Camera Application Platform (ACAP).

Cameras with an Artpec-6 and higher processor enable more than two overlays in a stream and multiple independent graphics in one Video Channel (View Area). Please take into account that more than 4 active services per Video Channel can be in conflict with Axis overlay. Also, to stay in the safe zone, a maximum of eight services running in all video channels is recommended. Also, be aware of a load of your camera if you are using a large number of animated services e.g. scrolling text in InfoTicker.

Global Parameters

CamOverlay App functionality can be controlled using API once the application is installed and licensed. There are several parameters described below. You can list all of them or just a single parameter by HTTP call:

http://IPADDR[:PORT]/axis-cgi/param.cgi?action=list&group=CamOverlay[.PARAMNAME]

where

IPADDR[:PORT] is an IP address:port of the camera. E.g. 192.168.1.5
PARAMNAME is a name of any parameter.

Any parameter can be changed using a HTTP call to the camera:

http://IPADDR[:PORT]/axis-cgi/param.cgi?action=update&CamOverlay.PARAMNAME=PARAMVALUE

where

IPADDR[:PORT] is an IP address:port of the camera. E.g. 192.168.1.5
PARAMNAME is a name of any parameter listed below.
PARAMVALUE is a value you would like to save to CamOverlay App. Special characters in the value have to be urlencoded. See URL encoding

Parameter Enabled

Start or stop all overlays in cameras video stream. Valid values: 0, 1

How to get and change the whole configuration of services

Overlay Object

Every overlay has to have six required parameters:

id is an unique identifying number of the overlay.
enabled start or stop overlay in video stream. Because of camera restriction only two overlays can be enabled at once!
automationType set the way how the visibility of overlay is controlled. (See automation section)
schedule is a schedule for enable/disable overlay.
name is an overlay type. Valid values: images, customGraphics, ptzCompass, infoticker, screenSharing, pip, accuweather
cameraList assigns graphics to selected Video Channels. Valid values: 0, 1, 2...
(till version 2.1.14 is used only camera with support for only one channel, versions 2.1.15 and higher are backward compatible with this parameter)

Get configuration of services

Complete settings of overlay services in JSON format can be obtained with GET call below. The base structure contains array "services" with overlay objects.

http://USER:PASS@IPADDR[:PORT]/local/camoverlay/api/services.cgi?action=get

where

USER is an user name. E.g. root
PASS is a password . E.g. pass
IPADDR[:PORT] is an IP address:port of the camera. E.g. 192.168.1.5

Example of what you get:

{
"services": [
{
"id": 1,
"enabled": 1,
"automationType": "manual",
"cameraList": [
0
],
"schedule": "",
"name": "infoticker",
"customName": "",
"showClock": 1,
"clockType": "24h",
"textColor": "0,0,0,1",
"bgColor": "255,255,255,1",
"weatherLocation": "",
"weatherLocationName": "",
"weatherLang": "en-us",
"weatherUnits": "Metric",
"numberOfLines": 1,
"switchingTime": 5,
"crawlLeft": false,
"crawlSpeed": 1,
"coordSystem": "bottom",
"pos_y": 0.05,
"width": 1920,
"height": 1080,
"zIndex": 0,
"font": "classic",
"fontSize": 40,
"sourceType": "text",
"source": "",
"chosen": false,
"selected": false
},
{
"id": 5,
"enabled": 1,
"automationType": "time",
"cameraList": [
0
],
"schedule": "",
"name": "images",
"customName": "",
"width": 1920,
"height": 1080,
"zIndex": 0,
"overlayList": [
{
"active": false,
"coordSystem": "top_left",
"pos_x": 10,
"pos_y": 10,
"imgPath": "",
"imgName": "",
"duration": 5,
"scale": 1
}
]
}
]
}

Set the configuration of services

If you want to update your service settings, you must use POST call:

http://USER:PASS@IPADDR[:PORT]/local/camoverlay/api/services.cgi?action=set

where

USER is an user name. E.g. root
PASS is a password. E.g. pass
IPADDR[:PORT] is an IP address:port of the camera. E.g. 192.168.1.5.

GET request has a limit of 2048 characters (in Unicode). Updated information via the given HTTP requests is not saved persistently in the camera. Therefore, data is lost after a camera restart. In order to avoid the loss of information, it is necessary to update data on a regular basis or update the whole JSON CamOverlay App configuration via a POST request. (See section with SET example)

Automation

Automation is set via attribute automationType and can have the following values:
manual - control via the user interface of the app or HTTP request (below)
schedule - displaying of overlays based on the week schedule
inputX - X is the number of camera input, input 1 is set with number 0 (zero-based)

InvertInput
Parameter invertInput inverts the logic of graphics activation based on the port state. Possible values:
true - activates the graphics when the port state is 1
false - activates the graphics when the port state is 0

HTTP request to display/hide the particular overlay

For example:

http://USER:PASS@IPADDR[:PORT]/local/camoverlay/api/enabled.cgi?SERVICE_ID=PARAMVALUE&SERVICE_ID=PARAMVALUE

where

USER is an user name. E.g. root
PASS is a password . E.g. pass
IPADDR[:PORT] is an IP address:port of the camera. E.g. 192.168.1.5
SERVICE_ID is an ID of overlay service which you want to change and is written as id_X, X is the number of the service, id_X can be replaced with name_myservice, name_myservice=1 enables service with name "myservice"
PARAMVALUE show or hide a particular overlay. Valid values: 0, 1

Updated information via the given HTTP requests is not saved persistently in the camera. Therefore, data is lost after a camera restart. In order to avoid the loss of information, it is necessary to update data on a regular basis or update the whole JSON CamOverlay App configuration via a POST request. (See section with SET example)

Service parameters

Images Parameters

width is a width of the stream for which the overlay is set.
height is a height of stream for which the overlay is set.
overlayList is an array of image objects. Every image object has parameters like position or duration (listed below).

Image Parameters

coordSystem is a start of coordinate system from which the offset is computed. Valid values: top_left, top_right, bottom_left, bottom_right, left, right, top, bottom, center
pos_x is an offset in pixels in X axis direction in video stream.
pos_y is an offset in pixels in Y axis direction in video stream.
imgPath is a path to image saved in the camera memmory or image url.
imgName is an identifier of an image in user interface.
duration is a duration of image in video stream.

Scripter Overlay Parameters

Scripter is service for external scripts which can render images with Websocket API (see section below).

identifier is just for identification of script which created this service.

API of services

Custom Graphics

It is possible to update texts in your text fields, switch between text variants, modify the position of graphics and change the background image.

Complete settings of service in JSON format can be obtained with GET call.

Update text and text colors in text fields

Following request updates texts in text fields. Conditions:
a) use your names of fields as identification
b) variations of text fields are numbered from 0 in API (text1 has index 0)

For example:

http://USER:PASS@IPADDR[:PORT]/local/camoverlay/api/customGraphics.cgi?action=ACTION&service_id=SERVICE_ID&FIELD_NAME=YOUR_TEXT&FIELD_NAME_COLOR=FIELD_TEXT_COLOR[&FIELD_NAME=YOUR_TEXT]

http://USER:PASS@IPADDR[:PORT]/local/camoverlay/api/customGraphics.cgi?action=ACTION&service_id=SERVICE_ID&FIELD_NAME_INDEX=FIELD_INDEX_NUMBER

where

USER is an user name. E.g. root
PASS is a password. E.g. pass
IPADDR[:PORT] is an IP address:port of the camera. E.g. 192.168.1.5
ACTION this parameter has two possible values update_text or update_image.
SERVICE_ID is an ID of overlay service which you want to change, service_id can be replaced with service_name which uses a custom name filled in each service
FIELD_NAME is an ID of particular text field with default or changed name.
YOUR_TEXT is your title.
FIELD_NAME_COLOR is an ID of particular text field color. E.g. field1_color.
FIELD_TEXT_COLOR is a color defined as 255255255 or with an alpha channel as 255255255255.
FIELD_NAME_INDEX is an ID of a particular text field variant. E.g. field1_index.
FIELD_TEXT_NUMBER is a number of a particular text field variant. E.g. 0 for text1.

Modification of the background image

All parameters are optional except service_id and action

Update of the picture from your storage

curl -u USER:PASS -X POST --data-binary "@PATH_TO_THE_PICTURE" "http://IPADDR[:PORT]/local/camoverlay/api/customGraphics.cgi?action=update_image&service_id=SERVICE_ID"

where

USER is an user name. E.g. root
PASS is a password. E.g. pass
IPADDR[:PORT] is an IP address:port of the camera. E.g. 192.168.1.5
PATH_TO_THE_PICTURE the path to your picture on the storage.
SERVICE_ID is an ID of overlay service which you want to change, service_id can be replaced with service_name which uses a custom name filled in each service

Update of the picture from camera storage

http://USER:PASS@IPADDR[:PORT]/local/camoverlay/api/customGraphics.cgi?action=update_image&service_id=SERVICE_ID&image=PATH_TO_THE_PICTURE

Update of the picture position

You can combine pos_x, pos_y and coord_system

http://USER:PASS@IPADDR[:PORT]/local/camoverlay/api/customGraphics.cgi?action=update_image&service_id=SERVICE_ID&coord_system=COORDSYSTEM&pos_x=POSX&pos_y=POSY

where

COORDSYSTEM is a start of coordinate system from which the offset is computed. Valid values: top_left, top_right, bottom_left, bottom_right, left, right, top, bottom, center
POSX is an offset in pixels in X axis direction in video stream.
POSY is an offset in pixels in Y axis direction in video stream.

Info Ticker

In Info Ticker, text can be set into video stream directly by HTTP API call.

HTTP API call for text change:

http://USER:PASS@IPADDR[:PORT]/local/camoverlay/api/infoticker.cgi?service_id=SERVICEID&text=YOUR_TEXT

where

USER is an user name. E.g. root
PASS is a password . E.g. pass
IPADDR[:PORT] is an IP address:port of the camera. E.g. 192.168.1.5
SERVICEID is an ID of overlay service which you want change.
YOUR_TEXT is your title.

WebSocket API

Over the WebSocket connection, you can receive information about the status of services and about their turning on and off. WebSockets are available from version 2.1.7

Authorization

Get authorization token for WebSocket API. The token is valid only for 30 seconds or until the first connection.

Request:

http://USER:PASS@IPADDR[:PORT]/local/camoverlay/api/ws_authorization.cgi

where

USER is a user name. E.g. root
PASS is a password. E.g. pass

IPADDR[:PORT] is an IP address:port of the camera. E.g. 192.168.1.5

Response:

{
  "status": 200,
  "message": "YZWG1nBG7HtRc8Owy61P",
}

Connection to WebSocket

You must use authorization as the first message. After successful authorization, the initialization data are sent. On authorization error, WebSocket is closed.

Used protocol (Sec-WebSocket-Protocol) is events

WebSocket address:

wss://IPADDR[:PORT]/local/camoverlay/service/ws

where

IPADDR[:PORT] is an IP address:port of the camera. E.g. 192.168.1.5

Request:

{
  "authorization": "80aXr8Vm0iFZl3Rlo2tR"
}

Response:

{
  "type": "authorization",
  "state": "OK"
}

To resend initialization data user request below.

Request:

{
  "command": "sendInitData"
}

Response:

{
  "type": "init",
  "data": {
    "type": "ServiceStart",
    "serviceId": 2
  }
}

Type of events

ServiceStart - attributes: type, serviceId

{"type":"ServiceStart","serviceId":2}

ServiceStop - attributes: type, serviceId

{"type":"ServiceStop","serviceId":2}

Realtime drawing API

There is a possibility to draw your own graphic directly in the camera using CamOverlay WebSocket API. This technology is used for example by CamScripter App for the custom integrations of another systems. The drawing API is based on Cairo graphic library (https://cairographics.org/) expanded with some help functions and functions needed by CamOverlay App. However, not all functions from the Cairo library are implemented. There is only a subset which will be extended in the future if it is required. All communication through WebSocket is done in JSON format. Client sends command with call_id and response always contains same ID for command identification.

For example we can create image by sending command:

{"call_id": 0, "command": "cairo_image_surface_create", "params": ["CAIRO_FORMAT_ARGB32", 200, 200]}

Response:

{"var": "surface0", "call_id": 0}

Variable name surface0 can be used for accessing this variable in other functions: cairo_create(cairo_surface_t *target). For simplification it is recommended to use CamStreamer node.js library created for CamScripter App (here). There are also some more examples of usage.

Currently implemented Cairo functions

Image Surfaces

cairo_image_surface_create(cairo_format_t format, int width, int height)

cairo_surface_write_to_png(cairo_surface_t *surface, const char *filename)

cairo_surface_destroy(cairo_surface_t *surface)

Paths

cairo_rectangle(cairo_t *cr, double x, double y, double width, double height)

cairo_move_to(cairo_t *cr, double x, double y)

cairo_line_to(cairo_t cr, double x, double y)

cairo_new_sub_path(cairo_t cr)

cairo_close_path()

cairo_arc(cairo_t *cr, double xc, double yc, double radius, double angle1, double angle2)

Cairo

cairo_create(cairo_surface_t *target)

cairo_destroy(cairo_t *cr)

cairo_save(cairo_t *cr)

cairo_restore(cairo_t *cr)

cairo_set_source_rgb(cairo_t *cr, double red, double green, double blue)

cairo_set_source_rgba(cairo_t *cr, double red, double green, double blue, double alpha)

cairo_fill(cairo_t *cr)

cairo_stroke(cairo_t *cr)

cairo_set_line_width(cairo_t *cr, double width)

cairo_surface_flush(cairo_surface_t *surface)

cairo_set_source_surface(cairo_t *cr, cairo_surface_t *surface, double x, double y)

cairo_paint(cairo_t *cr)

cairo_clip(cairo_t *cr)

cairo_reset_clip(cairo_t *cr)

Transformations

cairo_translate(cairo_t *cr, double tx, double ty)

cairo_scale(cairo_t *cr, double sx, double sy)

cairo_rotate(cairo_t *cr, double angle)

cairo_set_matrix(cairo_t *cr, const cairo_matrix_t *matrix)

cairo_get_matrix(cairo_t *cr, cairo_matrix_t *matrix)

cairo_identity_matrix(cairo_t *cr)

Text

cairo_show_text(cairo_t *cr, const char *utf8)

cairo_set_font_size(cairo_t *cr, double size)

cairo_text_extents(cairo_t *cr, const char *utf8, cairo_text_extents_t *extents)

cairo_set_font_face(cairo_t *cr, cairo_font_face_t *font_face)

Font

cairo_font_face_destroy(cairo_font_face_t *font_face)

Extended functions

write_text(cairo_t *cr, const char * text, const int x, const int y, const int width, const int height, const char *align, const char *textFitMethod)

Write text to box on position x, y, width, height [px]. Align should be one of the values: A_LEFT, A_RIGHT, A_CENTER.
TextFitMethod options:
TFM_SCALE - Text size is adjusted to width and height of the box.
TFM_TRUNCATE - Text size truncated to the width of the box.
TFM_OVERFLOW - Text overflows the box.

upload_image_data(const char * base64)

Upload image to the CamOverlay App and return variable name and dimensions of that image.

upload_font_data(const char * base64)

Upload font to the CamOverlay App and return variable name.

matrix_destroy(cairo_matrix_t *matrix)

Release allocated memory for matrix.

show_cairo_image_v2(cairo_surface_t *surface, const double x, const double y, const int * cameraList, const int zIndex)

Show image in CamOverlay App on positions x, y. The positions in coordinates -1.0,-1.0 (upper left) / 1.0,1.0 (bottom right). The image is shown in all video channels specified by cameraList with the given zIndex.

Deprecated:

remove_image(const int serviceID)

Remove the image in the CamOverlay App service with the given ID.