CamOverlay App API Documentation

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

Parameters


CamOverlay 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. 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


Parameter Services

Complete setting of overlay services in JSON format. Base structure contains object "services" which is an array of overlay objects (listed below).

{
    "services": [{
        "id": 1,
        "enabled": 0,
        "schedule": "",
        "name": "custom",
        "width": 1920,
        "height": 1080,
        "overlayList": [{
            "coordSystem": "top_left",
            "pos_x": 10,
            "pos_y": 10,
            "imgPath": "file:///usr/local/packages/camoverlay/localdata/user_images/bg-title.png",
            "imgName": "bg-title.png",
            "duration": 5
    }, {
        "id": 2,
        "enabled": 0,
        "schedule": "",
        "name": "scripter",
        "identifier": "test script"
    }, {
        "id": 3,
        "enabled": 1,
        "schedule": "",
        "name": "instant",
        "scale": 1.0,
        "width": 1920,
        "height": 1080
    }]
    }
}
        

Overlay Object

Every overlay have to have four required parameters:

id is an unique identifying number of the overlay.
enabled start or stop overlay in video stream. Because of camera resctriction only two overlays can be enabled at once!
schedule is a schedule for enable/disable overlay.
name is an overlay type. Valid values: custom, instant


Custom Overlay 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.


Instant Overlay Parameters

width is a width of stream for which the overlay is set.
height is a height of stream for which the overlay is set.
scale is a scale of all images.


Instant Overlay HTTP API

In Instant overlay, title or image can be set into video stream directly by HTTP API calls.

Title can be displayed by HTTP API call:

http://USER:PASS@IPADDR[:PORT]/local/camoverlay/api/instant.cgi?action=show&service_id=SERVICEID[&coord_system=COORDSYSTEM[&pos_x=POSX[&pos_y=POSY[&line1=LINE1[&line2=LINE2]]]]]

where

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 can change.
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.
LINE1 is a text shown on the first line of titling.
LINE2 is a text shown on the second line of titling.


Image can be displayed by HTTP API call:

http://USER:PASS@IPADDR[:PORT]/local/camoverlay/api/instant.cgi?action=show&service_id=SERVICEID[&coord_system=COORDSYSTEM[&pos_x=POSX[&pos_y=POSY[&img_path=IMGPATH[&fullscreen=FULLSCREEN]]]]]

where

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 can change.
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.
IMGPATH is a path to image saved in camera o
FULLSCREEN stretch image to fullscreen. Valid values: 0, 1

Image can be also uploaded in multipart/form post data directly into the stream:

curl -X POST -F "image=@image.png" "http://USER:PASS@IPADDR[:PORT]/local/camoverlay/api/instant.cgi?action=show&service_id=SERVICEID[&coord_system=COORDSYSTEM[&pos_x=POSX[&pos_y=POSY[&fullscreen=FULLSCREEN]]]]

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 can change.
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.
IMGPATH is a path to image saved in the camera memmory or image url.
FULLSCREEN stretch image to fullscreen. Valid values: 0, 1

Image can be removed from camera by HTTP API call:

http://USER:PASS@IPADDR[:PORT]/local/camoverlay/api/instant.cgi?action=clear_all&service_id=SERVICEID

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 can change.



Info Ticker

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

HTTP API call for text change:

curl --user USER:PASS "http://IPADDR[:PORT]/local/camoverlay/api/infoticker.cgi?service_id=SERVICEID" -d "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 can change.
YOUR_TEXT is your title.



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 (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

cairo_create(cairo_surface_t *target)
cairo_destroy(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)

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)

Write text to box on position x, y, width, height [px]. Align should be one of the values: A_LEFT, A_RIGHT, A_CENTER.

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(const int serviceID, cairo_surface_t *surface, const double x, const double y)

Show image in CamOverlay App service with given ID (it should be service of type scripter) on positions x, y. Position is in coordinates -1.0,-1.0 (upper left) / 1.0,1.0 (bottom right).



Feel free to contact our support in case of any problem.