Changes in overlay modifications through parameter CGI

• Having multiple API’s competing for mutual hardware resources is a common cause for misconception. By making this change we are unifying the ways overlays are handled.
• The dynamicoverlay CGI is a modern API with more features. param.cgi can only control the one and the first overlay from the dynamic API whereas dynamic overlay API can control multiple overlays.

• The parameter CGI’s overlay parameters will, for now, work almost as before. The difference is that overlays created through this API will be part of the same system as overlays created through dynamicoverlay CGI and the camera GUI. This unification of ownership will cause less ambiguity when it comes to the mutual resources and will also result in a unified look and feel for all overlays, regardless which API was used to create them.
• There will no longer be a clear distinction between overlays created via parameter CGI and overlays created through the camera GUI/dynamicoverlay CGI. This means that an overlay created via parameter CGI can be modified or removed by dynamicoverlay CGI, and vice versa. Even if the internal workings have been unified, both APIs still have a list on their own about their idea of the current overlay state.
• We discourage using the parameter CGI and dynamicoverlay CGI at the same time as it may cause mismatches between the believed overlay state and the actual overlay state for each API.

The major difference between the APIs is that dynamicoverlay CGI is a HTTP POST API, as opposed to parameter CGI which is a HTTP GET API. POST refers to the client used to send the message, such as curl or postman.

Create a Text Overlay

• parameter CGI:

http://<srv>/axis-cgi/param.cgi?action=update&Image.I0.Text.TextEnabled=yes&Image.I0.Text.String=TEST

• dyanmicoverlay CGI:

http://<srv>/axis-cgi/dynamicoverlay/dynamicoverlay.cgi

POST {"apiVersion": "1.0", "method": "addText", "params": {“camera”: 1, "text": "TEST”}}

The calls here are similar, the main difference being the way we communicate with the API, and that channel (I0, I1 etc.) has been replaced by camera, which starts at 1 instead.

Update a Text Overlay with position at bottom, with YY-MM-DD date and text

• parameter CGI:

http://<srv>/axis-cgi/param.cgi?action=update&Image.I0.Text.TextEnabled=yes
&Image.I0.Text.String=TEST&Image.I0.Text.Position=bottom&Image.I0.Text.DateEnabled=yes

• dyanmicoverlay CGI:

http://<srv>/axis-cgi/dynamicoverlay/dynamicoverlay.cgi

POST {"apiVersion": "1.0", "method": "setText", "params": {“identity”: 1, “position”:”bottom”, "text": "%F TEST”}}

Since there is only a single overlay slot for each image channel in parameter CGI, updating is done by overwriting existing values. When using dynamicoverlay CGI, we must explicitly state which overlay we use to update, since we can have several for each image channel. The identity of an overlay is returned upon creation. Furthermore, we see a difference in that there is no explicit setting for enabling the date. Instead, we use the modifier string directly in the text field. Modifiers are already usable via parameter CGIs text field, so nothing is new here.

Create a Text Overlay with large font size, black text color, white background, and the clock

• parameter CGI:

http://<srv>/axis-cgi/param.cgi?action=update&Image.I0.Text.TextEnabled=yes&Image.I0.Text.TextSize=large&Image.I0.Text.ClockEnabled=yes
&Image.I0.Text.Color=black&Image.I0.Text.BGColor=white

• dynamicoverlay CGI:

http://<srv>/axis-cgi/dynamicoverlay/dynamicoverlay.cgi

POST {"apiVersion": "1.0", "method": "addText", "params": {“camera”: 1, “fontSize”: 32, “textBGColor”: ”white”, “textColor”: “black”, "text": "%X”}}

As we saw in the last example, we once again use the modifier in the text field directly, instead of explicitly enabling the clock. Another difference is the fontSize-field, which now is expressed as an integer instead of a string. The mapping is as follows: small = 16, medium = 24, large = 32

Create an Image Overlay at custom position

• parameter CGI:

http://<srv>/axis-cgi/param.cgi?action=update&Image.I0.Overlay.Enabled=yes&Image.I0.Overlay.XPos=900
&Image.I0.Overlay.YPos=70&Image.OverlayPath=/etc/overlays/axis(128x44).ovl

• dyanmicoverlay CGI:

http://<srv>/axis-cgi/dynamicoverlay/dynamicoverlay.cgi

POST {"apiVersion": "1.0", "method": "addImage", "params": {“camera”: 1, “overlayPath”: “/etc/overlays/axis(128x44).ovl”, “position”, “0,0”}}

Adding an image is like adding a text for both APIs. One difference is that position is no longer expressed as an absolute value based on screen resolution, but as a relative value between -1.0 and 1.0, or as a string (top, bottomLeft etc.).

Updating the image overlay is done in the same way as updating the text overlay, but for images we call setImage instead.

• VAPIX Library