Overlay API

The API consists of a CGI enabling a user to control the underlaying dynamic overlays. There is one CGI request that implements a number of methods and to which the responses are in the JSON format.

The CGI gives the client the ability to:

• Create image overlays.

• Create text overlays.

• Alter properties on a previously created overlay.

• Remove a given overlay.

• List created overlays.

• Request a list with the supported API versions.

Note:

• All of the overlays, especially those that are neither text nor image overlays, can be modified by internal applications.

• The coordinate system used in this API is [-1.0,1.0] for both the X and Y axis. In addition to the coordinate system there are also several named positions, such as topLeft.

• The maximum number of characters for each individual text overlay is 512.

Property

Properties.API.HTTP.Version=3

Property

Properties.DynamicOverlay.DynamicOverlay=yes

Property

Properties.DynamicOverlay.Version=1.00

Firmware

7.10 and later

The Dynamic overlay API replaces the previously used Image overlay and Text overlay API that were both using the param.cgi parameter.

The implementation uses the same resources as param.cgi. It is possible to use dynamicoverlay.cgi to change overlays created with param.cgi and vice versa. However, using both dynamicoverlay.cgi and param.cgi for overlay handling may lead to unexpected behavior.

Overlay IDs may change after a reboot. This is because the overlay system always uses the lowest available number, starting from 1.

The examples in the following sections are formatted to be used with cURL.

$ curl --anyauth -H "Content-Type: application/json" --data @sample_code.json
https://$ip/axis-cgi/dynamicoverlay/dynamicoverlay.cgi

Use this example to add text overlays with transparent backgrounds, in this case one at the top left corner of the video that shows timestamps and another at the right bottom corner that shows the address and location of the camera.

1. Add a text overlay at the top left corner that shows the timestamp. If the font size is not specified by the user a suitable font size will be selected by the camera depending on resolution. The font size will then have to be read back with a list command should the user require it.

{
  "apiVersion": "1.0",
  "context": "321",
  "method": "addText",
  "params": {
    "camera": 1,
    "text": "%c",
    "position": "topLeft",
    "textColor": "white"
  }
}

2. Parse the JSON response.

a. Success response example. The response returns the identity of the overlay created.

{
  "apiVersion": "1.0",
  "method": "addText",
  "context": "321",
  "data": {
    "camera": 1,
    "identity": 0
  }
}

b. Failure response example.

{
  "apiVersion": "1.0",
  "method": "addText",
  "context": "321",
  "error": {
    "code": 304,
    "message": "Invalid value for parameter text"
  }
}

3. Add a text overlay at the bottom right corner that shows the address using a specified font size.

{
  "apiVersion": "1.0",
  "context": "456",
  "method": "addText",
  "params": {
    "camera": 1,
    "text": "Emdalav/u00E4gen 14\nLund",
    "position": "bottomRight",
    "fontSize": 14,
    "textColor": "white"
  }
}

4. Parse the JSON response.

a. Success response example. The response returns the identity of the overlay created.

{
  "apiVersion": "1.0",
  "method": "addText",
  "context": "456",
  "data": {
    "camera": 1,
    "identity": 1
  }
}

b. Failure response example.

{
  "apiVersion": "1.0",
  "method": "addText",
  "context": "456",
  "error": {
    "code": 300,
    "message": "Unable to create overlays (limit reached)"
  }
}

API references:

Use this example to add an image overlay at the left bottom corner of the video.

General preparations

Upload an image:

POST /axis-cgi/call_overlay_upload.cgi?action=upload HTTP/1.0
Content-Type: multipart/form-data; boundary=----636f72676965
Content-Length: [...]
------636f72676965
Content-Disposition: form-data; name="fileInput"; filename="logo.ovl"
Content-Type: text/html
[...]
------636f72676965

An overlay can contain several bitmap images to be adaptable to different resolutions. By calling the list command, the user receives a list showing all of the available pictures.

The user may then call the addImage command to create an image overlay. The overlays present are:

/etc/overlays/axis(128x44).ovl
/etc/overlays/logo.ovl

where /etc/overlays/axis(128x44).ovl comes pre-installed.

By calling the list command a second time, the user receives information on all of the overlays, including the newly created overlay. In the description of the overlay is a variable called scalable that let the user know if the overlay is scale-to-resolution or not. Scale-to-resolution means that the image overlay re-scale based on the resolution of the video stream.

1. Add an image overlay at the default location with a company logo.

{
  "apiVersion": "1.0",
  "context": "789",
  "method": "addImage",
  "params": {
    "camera": 1,
    "overlayPath": "logo.ovl"
  }
}

2. Parse the JSON response.

a. Success response example. The response returns the identity of the overlay created.

{
  "apiVersion": "1.0",
  "method": "addImage",
  "context": "789",
  "data": {
    "camera": 1,
    "identity": 2
  }
}

b. Failure response, see

API references

Use this example to retrieve a list of all overlays used in a device.

1. List all overlays previously created by add methods.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "list",
  "params": {
  }
}

2. Parse the JSON response.

a. Success respons example. The response gives a list of overlays with all corresponding properties. Note that scale-to-resolution overlays are only listed as a single directory as described in for the add image overlay usecase. If the overlay is scaled to the resolution, then the scalable property should be set to true.

{
  "apiVersion": "1.0",
  "data": {
    "imageFiles": [
      "/etc/overlays/axis(128x44).ovl",
      "/etc/overlays/logo.ovl"
    ],
  "imageOverlays": [
    { "camera": 1, "identity": 2, "overlayPath": "logo.ovl", "position": ... },
    ...
  ],
  "textOverlays": [
    { "camera": 1, "identity": 0, ... "text": ... "fontSize": 80, "size": [32, 48]},
    { "camera": 1, "identity": 1, ... "text": ... "fontSize": 14, "size": [47, 256]},
    ...
    ]
  },
  "method": "list",
}

b. Failure response, see

API references:

Use this example to

Set text overlay

1. Set text color to white and background to red.

{
  "apiVersion": "1.0",
  "context": "456",
  "method": "setText",
  "params": {
    "identity": 0,
    "textBGColor": "red"
  }
}

2. Parse the JSON response.

a. Success response example.

{
  "apiVersion": "1.0",
  "method": "setText",
  "data": {}
}

b. Failure response, see

API references:

Set image overlay

1. Update image overlay

Update overlay image.

{
  "apiVersion": "1.0",
  "context": "333",
  "method": "setImage",
  "params": {
    "identity": 2,
    "camera": 1,
    "overlayPath": "redlogo.ovl"
  }
}

2. Parse the JSON response.

a. Success response example.

{
  "apiVersion": "1.0",
  "method": "setImage",
  "context": "333",
  "data": {}
}

b. Failure response, see

API references:

Use this example to remove an overlay based on its ID.

1. Remove the overlay with a specified identity.

{
  "apiVersion": "1.0",
  "context": "444",
  "method": "remove",
  "params": {
    "identity": 1
  }
}

2. Parse the JSON response.

a. Success response example.

{
  "apiVersion": "1.0",
  "method": "remove",
  "context": "444",
  "data": {}
}

b. Failure response, see .

API references:

Use this example to check if features are supported before an application uses them.

1. Get a list of supported JSON API versions. Note that no apiVersion is supposed to be defined in the request.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getSupportedVersions"
}

2. Parse the JSON response to find out whether the operation was successful or not.

a. Success response example.

{
  "method": "getSupportedVersions",
  "data": {
    "apiVersions": [
      {"1.0"},
      {"2.0"},
      {"3.0"},
    ]
  }
}

b. Failure response, see

API references:

Use this example to receive information about how many overlays that can be used.

1. Get the overlay capabilities for this camera.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "getOverlayCapabilities"
}

2. Parse the JSON response to find out whether the operation was successful or not.

a. Success response example.

{
  "method": "getOverlayCapabilities",
  "context": 123,
  "apiVersion": "1.0",
  "data": {
    "numberAvailbleSlots": 8,
    "slotsPerImageOverlay": 2,
    "slotsPerTextOverlay": 1
  }
}

b. Failure response, see

API references:

Use this example to implement an overlay with scrolling text when the text gets to long to fit in the video stream.

1. Create a text overlay at the bottom, then specify a background color to make the text easier to read. Set the scroll speed to negative to make the text move from right to left.

{
  "apiVersion": "1.0",
  "context": "123",
  "method": "addText",
  "params": {
    "camera": 1,
    "text": "Weather forecast: Sunny every day! --- Stock index OMSX +0.3%, ...",
    "scrollSpeed": -1,
    "position": "bottomRight",
    "textColor": "white",
    "textBGColor": "black"
  }
}

2. Parse the JSON response to find out whether the operation was successful or not.

a. Success response example.

{
  "apiVersion": "1.0",
  "method": "addText",
  "context": "123",
  "data": {
    "camera": 1,
    "identity": 1
  }
}

b. Failure response example.

{
  "apiVersion": "1.0",
  "method": "addText",
  "context": "123",
  "error": {
    "code": 310,
    "message": "Invalid value for parameter scroll speed"
  }
}

API references:

addText is used to create new text overlays. When creating an overlay using the CGI you may also specify properties at the same time.

Request

Security level

Operator

Method

POST

{
  "apiVersion": <string>,
  "context": <string>,
  "method": "addText",
  "params": {
    "camera": <1-x>,
    "text": <string>
    "position": <top|topRight|bottomRight|bottom|bottomLeft|topleft> | [decimal,decimal],
    "fontSize": <0-200>,
    "scrollSpeed": <(-20)-20>,
    "textColor": <black|white|red|transparent|semiTransparent>,
    "textBGColor": <black|white|red|transparent|semiTransparent>,
    "textOLColor": <black|white|red|transparent|semiTransparent>,
    "reference": <channel|source|sensor|scene>,
    "ptPosition": <(-180)-180>,
    "zoomInterval": <1-19999>,
    "indicator": <string>,
    "indicatorSize": <0-200>,
    "indicatorColor": <black|white|red|transparent|semiTransparent>,
    "indicatorBG": <black|white|red|transparent|semiTransparent>,
    "indicatorOL": <black|white|red|transparent|semiTransparent>
  }
}

• apiVersion The API version that the response should use.

• method="addText" Specifies that the addText operation is performed.

• context=<string> Optional. The user sets this value and server echoes the data in the response. If set, it will be present in the response regardless of whether the response is successful or an error.

• camera=<1-x> Required. Defines the view area on which the overall shall be displayed on. “x” is the number of available view areas on the product and can be found in Plain Config/Image/Nbr of configs.

• text=<string> Required. Defines text to be displayed.

• position=<top|topRight|bottomRight|bottom|bottomLeft|topLeft>|[decimal,decimal] Optional. Defines the x, y coordinates to place the overlay either by predefined strings or a relative x, y position consisting of an array of two numbers from -1.0 up to 1.0. Default is 0.0,0,0.

• textColor=<black|white|red|transparent|semiTransparent> Optional. Defines which color the text is displayed in. Default is black.

• textBGColor=<black|white|red|transparent|semiTransparent> Optional. Defines which background color to display. Default is transparent.

• textOLColor=<black|white|red|transparent|semiTransparent> Optional. Defines which outline color to display. Default is transparent.

• fontSize=<0-200> Optional. Defines the size of the text. Default size is determined relative to the maximal camera resolution, use “list” to get the actual size.

• reference=<channel|source|sensor|scene> Optional. Defines how the position coordinates are expressed. Default value is channel.

• When channel is the reference, the specified coordinates are relative to the video as it is seed by a user.

• When source is the reference, the specified coordinates are relative to the source image received from the sensor.

• When sensor is the reference, the coordinates are specified as pixels relative to the image sensor’s upper left corner.

• When scene is the reference, the overlay position consists of normalized pixel coordinate, like with channel. Pan and tilt values for the PTZ along with a zoom interval can also be used to define the overlay, while the pixel coordinates defines the position of the overlay in the camera image. The PTZ coordinates defines the pan and tilt position in degrees, where the overlay is places in the scene. The zoom interval determines between which zoom values the overlay will be visible.

• ptPosition=<(-180)-180>|[integer, integer] Optional. The pan/tilt coordinates of the PTZ, measured in degrees. Defines at which PTZ position an overlay is visible on the camera image. The coordinates should be given as an array of two integers between -180 to 180. The default pan and tilt values reflects the position of the camera from when the overlay was created.

• zoomInternval=<1-19999>|[integer, integer] Optional.

• scrollSpeed=<(-20)-20> Optional. This property is used to make the text slide across the stream instead of being stationary. Positive values cause the text to slide from left to right while negative values cause it to slide from right to left. When the text has fully left the stream it reappears on the other side. The default is 0. If textBGColor also is set the background will cover the whole width of the stream rather than only where the text is currently located.

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "apiVersion": "1.0",
  "method": "addText",
  "context": <string>,
  "data": {
    "camera": <integer>,
    "identity": <integer>
  }
}

• apiVersion Current version is 1.0.

• method="addText" The method described in this section.

• context=<string> Text-string echoed back if provided by the client in the corresponding request.

• data.camera The view area on which the overlay was created.

• data.identity The identity of the overlay created.

Return value - Failure

See

Error codes

The following table lists error codes that can be returned from this method. General errors are listed in .

addImage is used to create new image overlays. When creating an overlay using the CGI you may also specify properties at the same time.

Refer to the Overlay API section on uploading images for instruction on how to upload new images.

Request

Security level

Operator

Method

POST

{
  "apiVersion": <string>,
  "context": <string>,
  "method": "addImage",
  "params": {
    "camera": <1-x>,
    "overlayPath": <string>,
    "position": <top|topRight|bottomRight|bottom|bottomLeft|topLeft> | [decimal,decimal]
  }
}

• apiVersion The API version that the response should use.

• method="addImage" Specifies that the addImage operation is performed.

• context=<string> Optional. Client sets this value and server echoes data in the response. If set, it will be present in the response regardless of whether the response is successful or an error.

• camera=<1-x> Required. Defines the view area on which the overlay shall be displayed on. x is the number of available view areas on the product and can be found in Plain Config/Image/Nbr of configs.

• overlayPath=<string> Required. Defines path to image to display. Default is an empty string.

• position=<top|topRight|bottomRight|bottom|bottomLeft|topLeft> | [decimal,decimal] Optional. Defines the x,y coordinates to place the overlay either by predefined strings or a relative x,y position consisting of an array of two numbers from -1.0 up to 1.0. Default is 0.0,0.0.

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "apiVersion": "1.0",
  "method": "addImage",
  "context:" <string>,
  "data": {
    "camera": <integer>,
    "identity": <integer>
  }
}

• apiVersion Current version is 1.0.

• method="addImage" The method described in this section.

• context=<string> Text-string echoed back if provided by the client in the corresponding request.

• data.camera The view area on which the overlay was created.

• data.identity The identity of the overlay created.

Return value - Failure

See

Error codes

The following table lists error codes that can be returned from this method. General errors are listed in .

setText is used to update parameters for a certain text overlay. The user may specify more than one parameter at any time. Optional parameters that are not supplied will not be charged.

Request

Security level

Operator

Method

POST

{
  "apiVersion": <string>,
  "context": <string>,
  "method": "setText",
  "params": {
    "identity": <integer>,
    "text": <string>,
    "position": <top|topRight|bottomRight|bottom|bottomLeft|topLeft> | [decimal,decimal],
    "fontSize": <0-200>,
    "scrollSpeed": <(-20)-20>,
    "textColor": <black|white|red|transparent|semiTransparent>,
    "textBGColor": <black|white|red|transparent|semiTransparent>,
    "textOLColor": <black|white|red|transparent|semiTransparent>
  }
}

• apiVersion The API version that the response should use.

• method="setText" Specifies that the setText operation is performed.

• context=<string> Optional. Client sets this value and server echoes data in the response. If set, it will be present in the response regardless of whether the response is successful or an error.

• identity=<integer> Required. Defines which overlay to change.

• text=<string> Optional. Defines the text to be displayed.

• position=<top|topRight|bottomRight|bottom|bottomLeft|topLeft> Optional. Defines the x, y coordinates to place the overlay either by predefined strings or a relative x, y position consisting of an array of two numbers from -1.0 up to 1.0. Default is 0.0,0.0.

• textColor=<black|white|red|transparent|semiTransparent> Optional. Defines which color the text is displayed in.

• textBGColor=<black|white|red|transparent|semiTransparent> Optional. Defines which background color to display.

• textOLColor=<black|white|red|transparent|semiTransparent> Optional. Defines which outline color to display.

• fontSize=<0-200> Optional. Defines the size of the text.

• scrollSpeed=<(-20)-20> Defines the speed by which the text slides across the stream.

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "apiVersion": "1.0",
  "method": "setText",
  "context": <string>,
  "data": {}
}

• apiVersion Current version is 1.0.

• method="setText" The method described in this section.

• context=<string> Text-string echoed back if provided by the client in the corresponding request.

Successful calls contains an empty data object.

Return value - Failure

See

Error codes

The following table lists error codes that can be returned from this method. General errors are listed in .

setImage is used to update parameters for a certain image overlay. The user may specify more than one parameter at one time, however optional parameters that are not supplied will not be changed.

Request

Security level

Operator

Method

POST

{
  "apiVersion". <string>,
  "context": <string>,
  "method": "setImage",
  "params": {
    "identity": <integer>
    "overlayPath": <string>
    "position": <top|topRight|bottomRight|bottom|bottomLeft|topLeft> | [decimal,decimal]
  }
}

• apiVersion The API version that the response should use.

• method="setImage" Specifies that the setImage operation is performed.

• context=<string> Optional. Client sets this value and server echoes data in response. If set, it will be present in the response regardless of whether the response is successful or an error.

• identity=<integer> Required. Defines which overlay to change.

• overlayPath=<string> Optional. Defines path to image to display.

• position=<top|topRight|bottomRight|bottom|bottomLeft|topLeft> | [decimal,decimal] Optional. Defines the x, y coordinates to place the overlay either by predefined strings or a relative x, y position consisting of an array of two numbers from -1.0 up to 1.0. Default is 0.0,0.0.

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "apiVersion": "1.0",
  "method": "setImage",
  "context": <string>,
  "data": {}
}

• apiVersion Current version is 1.0.

• method="setImage" The method described in this section.

• context=<string> Text-string echoed back if provided by the client in the corresponding request.

Successful calls contains an empty data object.

Return value-Failure

See .

Error codes

The following table lists error codes that can be returned from this method. General errors are listed in .

list all overlays created by the add CGIs and display both their IDs and other properties. If specified, properties for all overlays can be listed for a given camera or, if further specified, for a specific camera layer. The IDs may change for each overlay after a reboot. It is therefore recommended to check the current overlay ID with list before it is updated or removed.

Request

Security level

Operator

Method

POST

{
  "apiVersion": <string>,
  "context": <string>,
  "method": "list",
  "params": {
    "camera": <1-x>,
    "identity": <integer>
  }
}

• apiVersion The API version that the response should use.

• method="list" Specifies that the list operation is performed.

• context=<string> Optional. Client sets this value and the server echoes data in the response. If set, it will be present in the response regardless of whether the response is successful or an error.

• camera=<1-x> Optional. Defines which view area we want to list properties for. Supplied either by the add or list CGIs. If not specified all view areas are listed.

• identity=<integer> Optional. Defines which specific overlay to list properties for.

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "apiVersion": "1.0",
  "method": "list",
  "context": <string>
  "data": {
    "imageFiles": ["fileName", "fileName"],
    "imageOverlays": [
      {
        "camera": <integer>,
        "identity": <integer>,
        "overlayPath": <string>,
        "position": [<decimal>,<decimal>] | <string>,
        "zIndex": <integer>,
        "visible": <boolean>
        "scalable": <boolean>
      }
    ],
    "textOverlays": [
      {
        "camera": <integer>,
        "identity": <integer>,
        "position": [<decimal>,<decimal>] | <string>,
        "text": <string>,
        "textColor": <string>,
        "textBGColor": <string>,
        "textOLColor": <string>,
        "fontSize": <integer>
        "scrollSpeed": <integer>,
        "size": [<integer>,<integer>],
        "zIndex": <integer>,
        "visible": <boolean>
        "scalable": <boolean>
      }
    ]
  }
}

• apiVersion Current version is 1.0.

• method="list" The method described in this section.

• context=<string> Text-string echoed back if provided by the client in the corresponding request.

• data.imageFiles[]=<list of image overlay files> List of file names available to use as image overlays, for example ["/etc/overlays/image1.ovl", "/etc/overlay/image2.ovl"]

• data.imageOverlays[].camera The view area.

• data.imageOverlays[].identity The overall identity.

• data.imageOverlays[].position The textual position string or x, y coordinates where the overlay is located.

• data.imageOverlays[].overlayPath The path to the image used for the overlay.

• data.imageOverlays[].zIndex If zIndex of the overlay.

• data.imageOverlays[].visible If the overlay is visible.

• data.imageOverlays[].scalable If the overlay is scaled, based on the resolution.

• data.textOverlays[].camera The view area.

• data.textOverlays[].identity The overlay identity.

• data.textOverlays[].position The textual position string or x, y coordinate where the overlay is located.

• data.textOverlays[].text The overlay text.

• data.textOverlays[].textColor The text color for the overlay.

• data.textOverlay[].textBGColor The background color for the overlay.

• data.textOverlay[].textOLColor The outline color for the overlay.

• data.textOverlay[].fontSize The outline color for the overlay.

• data.textOverlays[].scrollSpeed The scroll speed for the overlay.

• data.textOverlays[].size The actual size in pixels of the text overlay.

• data.textOverlays[].zIndex If zIndex of the overlay.

• data.textOverlays[].visible If the overlay is visible.

• data.textOverlays[].scalable If the overlay is scaled, based on the resolution.

Return value - Failure

See .

Error codes

The following table lists error codes that can be returned form this method. General errors are listed in .

remove will delete the overlay identified by the provided id.

Request

Security level

Operator

Method

POST

{
  "apiVersion": <string>,
  "context": <string>,
  "method": "<remove>",
  "params": {
    "identity": <integer>
  }
}

• apiVersion The API version that the response should use.

• method="list" Specifies that the +remove+1 operation is performed.

• context=<string> Optional. User sets this value and the server echoes the data in the response. If set, it will be present in the response regardless of whether the response is successful or an error.

• identity=<integer> Required. Defines which overlay to remove. Supplied either by the add or list CGIs.

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "apiVersion": "1.0",
  "method": "remove",
  "context": <string>,
  "data": {}
}

• apiVersion Current version is 1.0.

• method="remove" The method described in this section.

• context=<string> Text-string echoed back if provided by the client in the corresponding request.

All successful calls contains an empty data object.

Return value - Failure

See .

Error codes

The following table lists error codes that can be returned from this method. General errors are listed under .

getSupportedVersions is used to retrieve the list of supported response schema versions that are available.

Request

Security level

Operator

Method

POST

{
  "context": <string>,
  "method": "getSupportedVersions"
}

• method="getSupportedVersions" Specifies that the getSupportedVersions operation is performed.

• context=<string> Optional. Client sets this value and server echoes data in the response. If set, it will be present in the response regardless of whether the response is successful or an error.

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "method": "getSupportedVersions",
  "context": <string>,
  "data": {
    "apiVersions": ["<Major1>.<Minor1>", "<Major2>.<Minor2>"]
  }
}

• method="getSupportedVersions" The method described in this section.

• context=<string> Text-string echoed back if provided by the client in the corresponding request.

• data.apiVersions[]=<list of versions> List of supported versions, all major versions with highest supported minor version.

• <list of versions> List of "<Major>.<Minor>” versions e.g. [“1.4”, “2.5”].

Return value - Failure

HTTP code

200 OK

Content-type

application/json

{
  "method": "The called method",
  "context": "Echoed if provided by the client in the corresponding request",
  "error": {
    "code": integer error code,
    "message": "Error message"
  }
}

• method=<string> The method name.

• context=<string> Text-string echoed back if provided by the client in the corresponding request.

• error.code The error code.

• error.message The error message.

Error codes

There are no specific error codes for this method. General errors are listed under .

getOverlayCapabilities returns the number of total overlay slots, the number of slots occupied per text overlay and the number of slots occupied per image overlay.

Request

Security level

Operator

Method

POST

{
  "apiVersion": <string>,
  "context": <string>,
  "method": "getOverlayCapabilities"
}

• method="getOverlayCapabilities" Specifies that the getOverlayCapabilities operation is performed.

• context=<string> Optional. Client sets this value and server echoes data in the response. If set, it will be present in the response regardless of whether the response is successful or an error.

• apiVersion The API version that the response should use.

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "method": "getOverlayCapabilities",
  "context": <string>,
  "apiVersion": "1.0",
  "data": {
    "numAvailableSlots": <integer>,
    "slotsPerImageOverlay": <integer>,
    "slotsPerTextOverlay": <integer>
  }
}

• method="getOverlayCapabilities" The method described in this section.

• context=<string> Text-string echoed back if provided by the client in the corresponding request.

• apiVersion Current version is 1.0.

• data.numAvailableSlots=<integer> The number of slots available that can be used by overlays.

• data.slotsPerImageOverlay=<integer> The number of slots an image overlay occupies.

• data.slotsPerTextOverlay=<integer> The number of slots an text overlay occupies.

Return value - Failure

HTTP code

200 OK

Content-type

application/json

{
  "method": "The called method",
  "context": "Echoed if provided by the client in the corresponding request",
  "error": {
    "code": integer error code,
    "message": "Error message"
  }
}

• method=<string> The method name.

• context=<string> Text-string echoed back if provided by the client in the corresponding request.

• error.code The error code.

• error.message The error message.

Error codes

There are no specific error codes for this method. General errors are listed under .

General JSON error codes

The following table lists general error that can occur for any CGI method. Errors that are specific for a method are listed under the API description for that method.

Return value - Failure

If a request fails the response follows for the following syntax.

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": "Major.Minor",
  "method": "The called method",
  "context": "Echoed if provided by the client in the corresponding request",
  "error": {
    "code": integer error code,
    "message": "Error message"
}

• apiVersion=<string> Current version is 1.0.

• method=<string> The method name.

• context=<string> Text-string echoed back if provided by the client in the corresponding request.

• error.code The error code.

• error.message The error message.

The API consists of the single CGI overlaymodifiers.cgi which allows querying for supported overlay modifiers.

Property

Properties.OverlayModifiers.OverlayModifiers="yes"

Firmware

5.1 and later

This example will show you how to create a list of overlay modifiers for other users to choose from.

1. Retrieve a list of available groups and modifiers.

http://myserver/axis-cgi/overlaymodifiers.cgi

2. Parse JSON response.

{
  "apiVersion": "0.2",
  "context": 1,
  "method": "getOverlayModifiers",
  "data": {
    "groups": {
      "data": [
        {"mod": "%c"},
        {"mod": "%D"},
        {"mod": "%F"},
        {"mod": "%X"}
      ],
      ........
      "sysinfo": [
        {"mod": "#i"},
        {"mod": "#m"},
        {"mod": "#M"},
        {"mod": "#n"},
        {"mod": "#TC", "index": true},
        {"mod": "#TF", "index": true}
      ],
      ........
    }
  }
}

{
  "apiVersion": "0.2",
  "context": "1",
  "method": "getOverlayModifiers",
  "error": {
    "code": 1000,
    "message": "Internal Error"
  }
}

3. Create a list and present it to the user.

This method should be used when you want to retrieve overlay modifiers supported by your device.

Request

Security level

Operator

Method

GET

http://<servername>/axis-cgi/overlaymodifiers.cgi

Return value - Success

Returns available groups along with an array of modifiers.

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": "0.2",
  "context": 1,
  "method": "getOverlayModifiers",
  "data": {
    "groups": {
      "data": [
        {"mod": "%c"},
        {"mod": "%D"},
        {"mod": "%F"},
        {"mod": "%X"}
      ],
      ........
      "sysinfo": [
        {"mod": "#i"},
        {"mod": "#m"},
        {"mod": "#M"},
        {"mod": "#n"},
        {"mod": "#TC", "index": true},
        {"mod": "#TF", "index": true}
      ],
      ........
    }
  }
}

See for the JSON schema.

Return value - Failure

N/A, can only fail on a HTTP level.

"properties": {
  "mod": {"type": "string"},
  "index": {"type": "boolean"}
}

See for a complete list of available groups.

The shape of a privacy mask is defined by a list of corner coordinates that either forms a rectangle or a polygon. Which form that is supported is described by a property parameter.

• If Properties.PrivacyMask.Polygon=yes is active, then a simple polygon shape is supported byProperties.PrivacyMask.MaxNbrOfCorners corners .
  The corners should be sorted in a clockwise rotation around the polygon, however, it’s up to the client to decide on the starting corner.

• The other option supports 4 corners in the shape of a rectangle, where the corners should be sorted in a clockwise rotation starting at the upper left corner.

Property

Properties.API.HTTP.Version=3

privacymask.cgi in addition requires:

Property

Properties.PrivacyMask.PrivacyMask=yes

Property

Properties.PrivacyMask.MaxNbrOfPrivacyMasks=<number of supported privacy masks>

Property

Properties.PrivacyMask.Polygon=<yes/no>

Property

Properties.PrivacyMask.MaxNbrOfCorners=<int>

Property

 Properties.PrivacyMask.Query=<val1, val2, ...>

Property

ImageSource.NbrOfSources=<number of image sources>

Firmware

5.00 and later.

Product category

Network cameras with privacy mask support.

There currently exist two ways to create privacy masks. One is by using privacymask.cgi and the other by using param.cgi. Some functions, such as color and mosaic scale, can only be set using param.cgi, which means that some products will be using both.

• For cameras lacking support for privacymask.cgi, param.cgi is used on its own, as these cameras cannot adapt mask positions when the pan/tilt/zoom positions change, e.g. when connecting an external PTZ head on the serial port for a fix camera. Masks created on DPTZ are not affected by this.

• Cameras supporting the param.cgi use the “add”, “update” and “remove” options described in . Using the “add” option in the param.cgi will create new privacy masks denoted M0, M1 and M2, up to the maximum number of supported privacy masks.

1. Hardware dependent

The index in Image.I# represents the video channel.

The index in MaskWindows.M# represents the index of the privacy mask.

1. Hardware dependent

The index in Image.IO represents the video channel.

The index in MaskWindows.M# represents the index of the privacy mask.

Successful response privacymask.cgi

Response after a successful request to privacymask.cgi.

HTTP Code

204 No content

Content-type

text/plain

Error response privacymas.cgi

Response after an incorrectly formatted or incomplete request to privacymask.cgi.

HTTP Code

200 OK

Content-Type

text/plain

Error:
<Error message>

Successful response query=list

Response after a successful request to privacymask.cgi using query=list.

HTTP Code

200 OK

Content-Type

text/plain

<index1>:<Mask name1>
<index2>:<Mask name2>
...

Successful response query=listpxjson

Response after a successful request to privacymask.cgi using query=listpxjson.

HTTP Code

200 OK

Content-Type

application/json

{"listpx": [
    {"id": <int>,
      "name": "<Mask name 1>",
      "enabled": <true,false>,
      "zoomlowlimit": <int>,
      "position": [
        {"x": <int>, "y": <int>},
        ...
      ]
      "all_position": [
        {"x": <int>, "y": <int>},
        ...
      ]
    },
    ...
  ]
}

Pixel coordinates for a corner that is outside the current camera view will have values that are negative or larger than the image´s resolution.

Position array may contain up to Properties.PrivacyMask.MaxNbrOfCorners x/y pairs. If the privacy mask is not visible in the current camera position, an empty position array will be returned.

The all_position array contains the values found in position as well as all the positions and helper corners that have been added by the service.

Successful response query=position

Response after a successful request to the privacymask.cgi using query=position.

HTTP Code

200 OK

Content-Type

text/plain

pan=<float>
tilt=<float>
zoomlowlimit=<int>
width=<float>%
height=<float>%

Successful response query=positionpxjson

Response after a successful request to the privacymask.cgi using query=positionpxjson.

HTTP Code

200 OK

Content-Type

application/json

{"position": [
    {"x": <int>, "y": <int>},
    ...
  ],
}

Pixel coordinates for a corner that is outside the current camera view will have values that are negative or larger than the image´s resolution.

Position array may contain up to Properties.PrivacyMask.MaxNbrOfCorners x/y pairs. If the privacy mask is not visible in the current camera position, an empty position array will be returned.

Property

Properties.API.HTTP.Version=3

Firmware

5.00 and later.

The API consists of the following CGI:s:

• The uploadoverlayimage.cgi uses the following methods:

• The manageoverlayimages.cgi uses the following methods:

API Discovery

id=overlayimage

This API replaces the older .

Use this example to upload an image to use for an image overlay.

Upload image

1. Upload an image to the camera.

POST /axis-cgi/uploadoverlayimage.cgi HTTP/1.0
Content-Type: multipart/form-data; boundary=---------------------------735323031399963166993862150
Content-Length: [...]

-----------------------------735323031399963166993862150
Content-Disposition: form-data; name="json"
Content-Type: application/json

{
  "apiVersion": "1.0",
  "method": "uploadOverlayImage",
  "params": {
    "scaleToResolution": true,
    "alpha": "ffffff"
  }
}

-----------------------------735323031399963166993862150
Content-Disposition: form-data; name="image"; filename="image.bmp"
Content-Type: image/bmp
[Image data]
-----------------------------735323031399963166993862150

curl --request POST 'http://<ip-address>/axis-cgi/uploadoverlayimage.cgi'
--digest -s -u '<username>:<password>'
--form 'json=@"request.json"'
--form 'image=@"image.bmp"'
request.json

{
  "apiVersion": "1.0",
  "method": "uploadOverlayImage",
  "params": {
    "scaleToResolution": true,
    "alpha": "ffffff"
  }
}

2. Parse the JSON response.

a) Successful response. The response returns the path of the image.

{
  "apiVersion": "1.0",
  "method": "uploadOverlayImage",
  "data": {
    "path": /etc/overlays/image.ovl
  }
}

b) Error response.

{
  "apiVersion": "1.0",
  "method": "uploadOverlayImage",
  "error": {
    "code": "1003",
    "message": "Invalid parameter"
  }
}

API references

Use this example to list all available overlay images.

List images

1. List all available images.

{
  "apiVersion": "1.0",
  "method": "listImages",
}

2. Parse the JSON response.

a) Successful response example. The response list all available images. For each image a path identifying the image and a flag indicating the scaleWithResolution status is provided.

{
  "apiVersion": "1.0",
  "method": "listImages",
  "data": {
    "files": [
      {"path": "/etc/overlays/image1.ov1", "scaleWithResolution": true},
      {"path": "/etc/overlays/image2.ov1", "scaleWithResolution": false}
    ]
  }
}

b) Error response example.

{
  "apiVersion": "1.0",
  "method": "listImages",
  "error": {
    "code": "1003",
    "message": "Invalid parameter"
  }
}

API references

Use this example to delete an overlay image.

Delete image

1. Delete an image.

{
  "apiVersion": "1.0",
  "method": "deleteImage",
  "params": {
    "path": "/etc/overlays/image.ovl"
  }
}

2. Parse the JSON response.

a) Successful response example. The response will give information if the image was successfully deleted or not.

{
  "apiVersion": "1.0",
  "method": "deleteImage",
}

b) Error response example.

{
  "apiVersion": "1.0",
  "method": "deleteImage",
  "error": {
    "code": "1003",
    "message": "Invalid parameter"
  }
}

API references

Use this example to set a default overlay image.

1. Set the default image.

{
  "apiVersion": "1.0",
  "method": "setDefaultImage",
  "params": {
    "path": "/etc/overlays/image.ovl"
  }
}

2. Parse the JSON response.

a) Successful response example. The response will give information if the default image was correctly set or not.

{
  "apiVersion": "1.0",
  "method": "setDefaultImage",
}

b) Error response example.

{
  "apiVersion": "1.0",
  "method": "setDefaultImage",
  "error": {
    "code": "1003",
    "message": "Invalid parameter"
  }
}

API references

uploadOverlayImage is used to upload a new overlay image by using a multipart/form-data.

The first part should contain a JSON request and be set up with the following parameters:

Content-disposition

form-data; name="json"

Content-type

application/json

The second part should contain the image data and should be set up with the following parameters:

Content-disposition

form-data; name="image"; filename=<name of file>

Content-type

<image mime-type>

Request

Security level

Operator

Method

POST

{
  "apiVersion": <string>,
  "method": "uploadOverlayImage",
  "context": <string>,
  "params": {
    "scaleToResolution": <boolean>,
    "alpha": <string>
  }
}

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "apiVersion": "1.0",
  "method": "uploadOverlayImage",
  "context": <string>,
  "data": {
    "path": <string>
  }
}

Return value - Failure

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Error codes

See for a full list of potential error codes.

supportedFormats is used to get a list of image formats supported by the camera. Possible values are:

• bmp

• jpeg

• png

• svg

Request

Security level

Operator

Method

POST

{
  "apiVersion": <string>,
  "method": "supportedFormats",
  "context": <string>
}

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "apiVersion": "1.0",
  "method": "supportedFormats",
  "context": <string>,
  "data": {
    "formats": [<string>, <string>]
  }
}

Return value - Failure

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Error codes

See for a full list of potential error codes.

validateImageHeader will check if the image described by the parameters are supported, is of an acceptable file-size and that there are enough memory on the device. In cases where there are an invalid parameter, an error response is sent and the status code is set to reflect what the problem might be.

Request

Security level

Operator

Method

POST

{
  "apiVersion": <string>,
  "method": "validateImageHeader",
  "context": <string>,
  "params": {
    "type": <string>,
    "width": <int>,
    "height": <int>
  }
}

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "apiVersion": "1.0",
  "method": "validateImageHeader",
  "context": <string>,
  "data": {
    "supportsAlpha": <boolean>,
    "supportsScaling": <boolean>
  }
}

Return value - Failure

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Error codes

See for a full list of potential error codes.

listImages is used to get a list of available overlay images.

Request

Security level

Operator

Method

POST

{
  "apiVersion": <string>,
  "method": "listImages",
  "context": <string>
}

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "apiVersion": "1.0",
  "method": "listImages",
  "context": <string>,
  "data": {
    "files": [
      {"path": <string>, "scaleWithResolution": <boolean>},
      {"path": <string>, "scaleWithResolution": <boolean>}
    ]
  }
}

Return value - Failure

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": "listImages",
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Error codes

See for a full list of potential error codes.

deleteImage is used to delete an overlay image.

Request

Security level

Operator

Method

POST

{
  "apiVersion": <string>,
  "method": "deleteImage",
  "context": <string>,
  "params": {
    "path": <string>
  }
}

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "apiVersion": "1.0",
  "method": "deleteImage",
  "context": <string>
}

Return value-Failure

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Error codes

See for a full list of potential error codes.

getDefaultImage retrieves the currently configured default overlay image.

Request

Security level

Operator

Method

POST

{
  "apiVersion": <string>,
  "method": "getDefaultImage",
  "context": <string>
}

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "apiVersion": "1.0",
  "method": "getDefaultImage",
  "context": <string>,
  "data": {
    "path": <string>
  }
}

Return value - Failure

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Error codes

See for a full list of potential error codes.

setDefaultImage is used to set the default overlay image.

Request

Security level

Operator

Method

POST

{
  "apiVersion": <string>,
  "method": "setDefaultImage",
  "context": <string>
  "params": {
    "path": <string>
  }
}

Return value - Success

HTTP code

200 OK

Content-type

text/json

{
  "apiVersion": "1.0",
  "method": "setDefaultImage",
  "context": <string>
}

Return value - Failure

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Error codes

See for a full list of potential error codes.

getSupportedVersions is used to retrieve the list of supported API versions.

Request

Security level

Operator

Method

POST

http://<servername>/<functionality>.cgi

{
  "context": <string>,
  "method": "getSupportedVersions"
}

Return value - Success

HTTP code

200 OK

Content-type

application/json

{
  "context": <string>,
  "method": "getSupportedVersions",
  "data": {
    "apiVersion": ["<Major1>.<Minor1>", "<Major2>.<Minor2>"]
  }
}

Return value - Failure

HTTP code

200 OK

Content-type

application/json

{
  "apiVersion": "<Major>.<Minor>",
  "context": <string>,
  "method": <string>,
  "error": {
    "code": <integer error code>,
    "message": <string>
  }
}

Error codes

See for a full list of potential error codes.

Property

Properties.API.HTTP.Version=3

Firmware

5.00 and later.