vapix overlay api - axis communications · pdf fileoverlayapi...

VAPIX® VERSION 3

Overlay API

Overlay API

This document is copyright protected and is the property of Axis Communications AB and may not be copied, reproduced or distributed in any way withoutthe prior written consent of Axis Communications AB.

COPYRIGHT NOTICEThis document is copyright protected and is the property of Axis Communications AB and may not be copied, reproduced ordistributed in any way without the prior written consent of Axis Communications AB.

VAPIX® LICENSE AGREEMENTThis VAPIX® License Agreement (“License”) is a legal agreement between you (either individual or an entity) and Axis CommunicationsAB (“Axis”). By using the INTERFACE and INTERFACE DESCRIPTION (each defined below), whether in whole or in part, you agree to bebound by the terms of this License.

1. GRANT OF LICENSEAxis hereby grants to you the right to use the AXIS VAPIX application programming interface (“INTERFACE”) and the writtenspecification of the INTERFACE (the “INTERFACE DESCRIPTION”) for the sole and limited purpose of creating, manufacturing anddeveloping a solution that integrates any unit or portion included in the product range of Axis network products, as defined by Axis atits discretion (an “Axis Product”) and to market, sell and distribute any such solution.

2. COPYRIGHTThe INTERFACE and the INTERFACE DESCRIPTION are owned by Axis and are protected by copyright laws and international treatyprovisions. Any use of the INTERFACE and/or the INTERFACE DESCRIPTION outside the limited purpose set forth in Section 1above is strictly prohibited.

3. RESTRICTIONS ON USEYou have no rights with respect to the INTERFACE, INTERFACE DESCRIPTION or any portions thereof and shall not use the INTERFACE,INTERFACE DESCRIPTION or any portion thereof except as expressly set forth herein. You may not reverse engineer, decompile, ordisassemble the INTERFACE except to the extent required to obtain interoperability with other independently created computerprograms as permitted by mandatory law.

4. THIRD PARTY RIGHTSYou agree that you are fully responsible for your own conduct while using the INTERFACE and integrating any Axis Products intoyour solution and the consequences thereof. Axis Products may be combined with a virtually infinite number of potential solutions.Consequently, you recognize that (i) other third parties may claim to own patents or copyrights that could cover certain solutionswhich integrate Axis products, or which result from the combination of Axis products and additional technology or solutions and (ii)you are responsible for ensuring that any solution which integrates with an Axis Product, or a combination of a solution and an Axisproduct, does not infringe upon or misappropriate any intellectual property or personal right of any third party.

5. TERMINATIONThis License is effective until terminated. Your rights under this License will terminate automatically without notice from Axis if youfail to comply with any term(s) of this License. Upon the termination of this License, you shall cease all use and disposition of theINTERFACE and/or THE INTERFACE DESCRIPTION whether for the purpose set forth in Section 1 above or not.

6. REPRESENTATIONS AND WARRANTIES; DISCLAIMER6.1. You represent and warrant that (i) any solution created, manufactured and/or developed by you which integrates an Axis

Product shall not infringe or otherwise violate any third party rights, including but not limited to third party intellectualproperty rights; and (ii) your use of the INTERFACE and INTERFACE DESCRIPTION will comply with all applicable foreign anddomestic laws, rules and regulations.

6.2. YOUR USE OF THE INTERFACE IS AT YOUR SOLE RISK. THE INTERFACE AND THE INTERFACE DESCRIPTION ARE DELIVERED FREEOF CHARGE AND "AS IS" WITHOUT WARRANTY OF ANY KIND. THE ENTIRE RISK AS TO THE USE, RESULTS AND PERFORMANCEOF THE INTERFACE AND THE INTERFACE DESCRIPTION IS ASSUMED BY THE USER/YOU. AXIS DISCLAIMS ALL WARRANTIES,WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,FITNESS FOR A PARTICULAR PURPOSE, TITLE, NON-INFRINGEMENT AND PRODUCT LIABILITY, OR ANY WARRANTY ARISINGOUT OF ANY PROPOSAL, SPECIFICATION OR SAMPLE WITH RESPECT TO THE INTERFACE AND THE INTERFACE DESCRIPTION.Without limiting the generality of the foregoing, you acknowledge and agree that Axis does not make any representationor warranty that the integration of Axis Products into your solution does not infringe any third party rights. You are solelyresponsible for any intellectual property infringement claims that are based on or relate to solutions created, manufacturedand distributed by you which integrate Axis Products. Axis is unaware of the details regarding your particular solution,has not conducted any investigation relating to potential third party rights issues relating to your solution and does notaccept any responsibility or liability with respect thereto.

6.3. THIS LICENSE DOES NOT CONVEY ANY LICENSE TO THIRD PARTY INTELLECTUAL PROPERTY. YOU ARE SOLELY RESPONSIBLEFOR (I) EXAMINING WHETHER THE INTERFACE AND THE INTERFACE DESCRIPTION ARE ENCUMBERED BY OR INFRINGES UPONA RIGHT HELD BY A THIRD PARTY AND (II) ANY INTELLECTUAL PROPERTY INFRINGEMENT CLAIMS THAT ARISE OUT OF ORRELATE TO SOLUTIONS CREATED, MANUFACTURED AND DISTRIBUTED BY YOU WHICH INTEGRATE AXIS PRODUCTS.

2

Overlay API


7. LIMITATION OF LIABILITY7.1. AXIS SHALL NOT BE LIABLE FOR LOSS OF DATA, LOSS OF PRODUCTION, LOSS OF PROFIT, LOSS OF USE, LOSS OF CONTRACTS OR

FOR ANY OTHER CONSEQUENTIAL, ECONOMIC OR INDIRECT LOSS WHATSOEVER IN RESPECT OF USE OR DISPOSITION OF THEINTERFACE AND THE INTERFACE DESCRIPTION.

7.2. AXIS TOTAL LIABILITY FOR ALL CLAIMS IN ACCORDANCE WITH THE USE OF THE INTERFACE AND THE INTERFACE DESCRIPTIONSHALL NOT EXCEED THE PRICE PAID FOR THE INTERFACE AND THE INTERFACE DESCRIPTION.

7.3. YOU UNDERTAKE NOT TO PURSUE ANY CLAIMS WHATSOEVER AGAINST AXIS OR ITS AFFILIATES RELATING TO OR EMANATINGFROM THE INTERFACE AND THE INTERFACE DESCRIPTION OR YOUR INTEGRATION OF AN AXIS PRODUCT INTO YOUR SOLUTION.

8. INDEMNIFICATIONYou will indemnify and hold Axis, its subsidiaries, affiliates, officers, employees, and agents harmless from any and all claims,damages, losses, liabilities, actions, judgments, costs, and expenses brought by a third party, including claims for infringement ofintellectual property rights, arising out of or in connection with (i) your use of the INTERFACE or INTERFACE DESCRIPTION otherthan in accordance with the terms of this agreement, and/or (ii) any solution created, manufactured and/or developed by you whichintegrates an Axis Product.

9. GOVERNING LAWThis agreement shall be deemed performed in and shall be construed by the laws of Sweden. All disputes in connection withthis agreement shall be finally settled by arbitration in accordance with the Rules of the Arbitration Institute of the StockholmChamber of Commerce. The place of arbitration shall be Malmö, Sweden. The language of the proceedings, documentation andthe award shall be English.

3

Overlay API

Table of Contents

1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.2 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2 Privacy Mask API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.2.1 Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.3 Common Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.4 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.4.1 Image.I#.Overlay.MaskWindows . . . . . . . . . . . . . . . . . . . . . . . . . . 72.4.2 Image.I#.Overlay.MaskWindows.M# . . . . . . . . . . . . . . . . . . . . . . . 8

2.5 HTTP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.5.1 Privacy Mask Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92.5.2 Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

3 Text Overlay API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.2.1 Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.3 Common examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.4 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

3.4.1 Image.I#.Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.5 Modifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.6 HTTP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

3.6.1 Text Overlay Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173.6.2 Dynamic text overlay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

4 Image Overlay API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204.1 Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204.2 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.2.1 Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204.3 Common Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204.4 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.4.1 Image.I#.Overlay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204.4.2 Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

4.5 HTTP API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214.5.1 Image Overlay Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214.5.2 Upload image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

© 2011 - 2013 Axis Communications AB. AXIS COMMUNICATIONS, AXIS, ETRAX, ARTPEC and VAPIX are registered trademarks ortrademark applications of Axis AB in various jurisdictions. All other company names and products are trademarks or registeredtrademarks of their respective companies. We reserve the right to introduce modifications without notice.

4

Overlay API


1 Overview

1.1 DescriptionThis document describes the different overlay functionalities in VAPIX®. An overlay is a superimposed area over the video image, suchas a text, an image or a mask. The Overlay API is divided in Privacy Mask API, Text Overlay API and Image Overlay API.

1.2 ReferencesAll VAPIX® references are available at:

http://www.axis.com/vapix

5

Overlay API


2 Privacy Mask API

2.1 DescriptionPrivacy masks are configurable areas of solid color that allow concealment of parts of the image that should not be viewable. A mask isset in relation to the whole image source and does not change position if one or several view areas (if the Axis product supports it) areadded. Privacy masks can be configured in two ways on Axis products. In Axis products not supporting mechanical pan, tilt or zoomprivacy masks are set through parameters. In Axis products supporting privacy masks and supporting mechanical pan, tilt or zoom it ispossible to configure privacy masks via CGI requests (privacymask.cgi) or by parameters. The masks configured will adapt theirposition and size when the cameras pan/tilt/zoom position changes, to make sure that areas that have been masked stay masked.

2.2 Prerequisites

2.2.1 Identification

Property: Properties.API.HTTP.Version=3

privacymask.cgi in addition requires:

Property: Properties.PrivacyMask.PrivacyMask=yes

Firmware: 5.00 and later.Product category: Network cameras with privacy mask support.

2.3 Common ExamplesExample 1:Add a privacymask named mask1 in the center of the image. The width and the height of the mask are set in percent of theimage size.

http://myserver/axis-cgi/privacymask.cgi?action=add&name=mask1&width=20.0&height=20.0

Example 2:Add a privacy mask named mask1 using the param.cgi. The width and the height of the mask are 20 by 20 pixels and it ispositioned 100 pixels from the left corner and 500 pixels from the top.

http://myserver/axis-cgi/param.cgi?action=update&Image.I0.Overlay.MaskWindows.M0.Enabled=yes&Image.I0.Overlay.MaskWindows.M0.Width=20&Image.I0.Overlay.MaskWindows.M0.Height=20&Image.I0.Overlay.MaskWindows.M0.Xpos=100&Image.I0.Overlay.MaskWindows.M0.YPos=500&Image.I0.Overlay.MaskWindows.M0.Name=mask1

Example 3:Add a privacy mask named mask1 centered around 20% of image width and 30% of image height. Width and height are setin percent of the image size.

http://myserver/axis-cgi/privacymask.cgi?action=add&name=mask1&width=10.0&height=50.0&center=20.0,30.0

Example 4:Add a privacy mask named mask1 using pixel coordinates to set the position of the mask.

6

Overlay API


http://myserver/axis-cgi/privacymask.cgi?action=add&name=mask1&pxpolygon=100,100:200,100:200,200:100,200

Example 5:Add a privacy mask named mask1 using pan/tilt coordinates to set the position of the mask.

http://myserver/axis-cgi/privacymask.cgi?action=add&name=mask1&ptpolygon=-10.0,-10.0:10.0,-10.0:10.0,10.0:-10.0,10.0

Example 6:Adding a privacy mask named mask1. Width and height are set in percent of the image size. The mask will only appear if thezoom value is 200 or above.

http://myserver/axis-cgi/privacymask.cgi?action=add&name=mask1&width=20.0&height=20.0&zoomlowlimit=200

Example 7:Preview a mask that covers 30% of the image.

http://myserver/axis-cgi/privacymask.cgi?action=preview_on&width=30&height=30

Example 8:Query width and height for privacy mask p1.

http://myserver/axis-cgi/privacymask.cgi?query=position&name=p1

2.4 Parameters

2.4.1 Image.I#.Overlay.MaskWindows

[Image.I#.Overlay.MaskWindows]

Parameter Default values Valid values Access control Description

Color black blackgreywhitered

admin: read, writeoperator: read, write

Set the color forthe privacy masksof Image.I#.

black = Black coloredprivacy mask.grey = Grey coloredprivacy mask.white =White coloredprivacy mask.red = Red coloredprivacy mask.

7

Overlay API


2.4.2 Image.I#.Overlay.MaskWindows.M#

[Image.I#.Overlay.MaskWindows.M#]


Enabled no yesno


Enable/disable theprivacy mask.

yes = Enable theprivacy mask.no = Disable theprivacy mask.

PtPolygon1 <0.0,0.0:0.0,0.0:0.0,0.0:0.0,0.0>

A string. admin: read, writeoperator: read, write

Pan/tilt coordinatesof the corners of theprivacy mask stored asfloat values in a stringof coordinate pairs,pan1,tilt1:pan-2,tilt2:pan3,t-ilt3:pan4,tilt4.The first corner is theupper left corner, thesecond is the upperright, the third is thelower right and thefourth is the lower left.The range is -180 to180.

Name A string admin: read, writeoperator: read, write

The name of the privacymask.

ZoomLowLimit2 0 0...19999 admin: read, writeoperator: read, write

Hide the privacy mask ifthe current zoom valueis below the parametervalue.

YPos3 0 An unsigned integer. admin: read, writeoperator: read, write

The privacy masksupper left corner ispositioned at thishorizontal position (0 =at the top).

XPos3 0 An unsigned integer. admin: read, writeoperator: read, write

The privacy masksupper left corner ispositioned at thishorizontal position (0 =to the left.

Width3 0 An unsigned integer. admin: read, writeoperator: read, write

Width of mask, in pixels.

Height3 0 An unsigned integer. admin: read, writeoperator: read, write

Height of mask in pixels.

1. Available for products supporting pan, tilt or zoom.2. Product/release-dependent.3. Available for products without support for pan, tilt or zoom.

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

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

8

Overlay API


2.5 HTTP API

2.5.1 Privacy Mask Arguments

If the Axis product supports pan, tilt or zoom it is also possible to set privacy masks via the privacymask.cgi.

Access control: adminMethod: GET

Syntax:

http://<servername>/axis-cgi/privacymask.cgi?<argument>=<value>[<argument>=<value>...]

With the following parameters and values.

Argument Valid values Description

action=<string> add12update12remove1goto1preview_onpreview_off3

add = Add a new mask with uniquename.update = Change position and/or sizeof existing mask.remove = Remove an existing mask.goto = Center camera on an existingmask. For modifying existing masks.preview_on = Set a new or an existingmask in preview mode.preview_off = End preview on a newor an existing mask.

query=<query> listposition1

list = List all masks.position = List position and dimensioninformation about a mask.

name=<string> <string> Unique name to identify a mask.Maximum length is 31 characters.

width=<float> 0.0 ... 100.0 Width of mask, in percent of image width.

height=<float> 0.0 ... 100.0 Height of mask, in percent of imageheight.

center=<string> 0.0 ... 100.0,0.0 ...100.0 Center coordinates, in percentage ofimage width and image height, of themask stored as float values in a string,width,height. Used together withwidth and height parameters. If leftout the mask will be placed in the centerof the picture.

ptpolygon=<string> <0.0,0.0:0.0,0.0:0.0,0.0:0.0,0.0>

Pan/tilt coordinates of the corners of theprivacy mask stored as float values in astring of coordinate pairs, <pan1>,<t-ilt1>:<pan2>,<tilt2>:<pan3>,<tilt3>:<pan4>,<tilt4>. Thefirst corner is the upper left corner, thesecond is the upper right, the third is thelower right and the fourth is the lowerleft. The range is -180 to 180.

9

Overlay API


pxpolygon=<string> <0,0:0,0:0,0:0,0> Pixel coordinates of the corners ofthe privacy mask stored as integervalues in a string of coordinate pairs,<x1>,<y1>:<x2>,<y2>:<x3>,<y3>:<x4>,<y4>. The first corneris the upper left corner, the secondis the upper right, the third is thelower right and the fourth is the lowerleft. If no imageresolution orimagerotation argument is givenit is assumed that the pixel coordinatesare given in the default resolution of thecamera and with default rotation.

imagerotation=<int> 09041802704

The rotation of the image stream, usedfor the pixel coordinates.

0 = Rotate the image 0 degrees.90 = Rotate the image 90 degrees.180 = Rotate the image 180 degrees.270 = Rotate the image 270 degrees.

imageresolution=<string> <width>x<height> The resolution of the image stream, usedfor the pixel coordinates. In the format<width> times <height> number ofpixels.

zoomlowlimit=<int>4 0 ... 99995 Hide the privacy mask if the current zoomvalue is below the parameter value.

1. Requires name argument.2. Requires either width and height , pxpolygon or ptpolygon.3. The preview_off value on an existing mask (name is given), will reset the mask to previously saved position and size. The

preview_off value on a new mask (no name given) will remove the new mask.4. Product/release-dependent.5. If digital zoom is supported, zoomlowlimit can have values up to 19999.

2.5.2 Response

2.5.2.1 Successful response privacymask.cgi

Response after a successful request to the privacymask.cgi.

HTTP Code: 204 No contentContent-Type: text/plainBody: <Empty>

2.5.2.2 Error response privacymask.cgi

Response after an incorrectly formatted or incompleted request to the privacymask.cgi.

HTTP Code: 200 OKContent-Type: text/plain

Error:<Error message>

2.5.2.3 Successful response query=list

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

10

Overlay API



Body:

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

2.5.2.4 Successful response query=position

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


Body:

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

11

Overlay API


3 Text Overlay API

3.1 DescriptionThe text overlay is a text field that can be included in the top or bottom of the video image from an Axis product. The functionality canbe used for showing static text, Pan, Tilt and Zoom coordinates, preset positions, bit rate, etc. In addition to that it is also allowed toinsert dynamic text, for example from an application. The dynamic text is contained in the RAM memory only and is removed on boot.

3.2 Prerequisites


Property: Properties.API.HTTP.Version=3Firmware: 5.00 and later.

3.3 Common examplesExample 1:Enable text overlay and add “My Overlay” as text overlay.

http://myserver/axis-cgi/param.cgi?action=update&Image.I0.Text.TextEnabled=yes&Image.I0.Text.String=My%20Overlay

Example 2:Enable text overlay and add date and time using modifiers.

http://myserver/axis-cgi/param.cgi?action=update&Image.I0.Text.TextEnabled=yes&Image.I0.Text.String=%25F-%25H-%25M-%25S

Example 3:Enable text overlay and dynamic text overlay.

http://myserver/axis-cgi/param.cgi?action=update&Image.I0.Text.TextEnabled=yes&Image.I0.Text.String=%23D

Set the dynamic text overlay to "Test text" for cameras 1, 3 and 4.

http://myserver/axis-cgi/dynamicoverlay.cgi?action=settext&camera=1,3,4&text=Test%20text

Example 4:Get the dynamic text overlay from camera 2.

http://myserver/axis-cgi/dynamicoverlay.cgi?action=gettext&camera=2

3.4 Parameters

3.4.1 Image.I#.Text

To add a text overlay for all video formats the parameters in this group should be used.

12

Overlay API


[Image.I#.Text]


BGColor black whiteblacktransparentsemitransparent


Set the text backgroundcolor.

white = White textbackground colorblack = Black textbackground colortransparent= Transparent textbackground colorsemitransparent= Semi transperent textbackground color.

ClockEnabled no yesno


Show/hide the timestamp.

yes = Show the timestamp.no = Hide the timestamp.

Color white whiteblack


Set the text color.

white = White textcolor.black = Black textcolor.

DateEnabled no yesno


Show/hide the date.

yes = Show the date.no = Hide the date.

Position top topbottom


Position the text at thetop or at the bottom inthe image.

top = Position the textat the top in the image.bottom = Position thetext at the bottom inthe image.

String A string admin: read, writeoperator: read, write

Set the overlay text.The string must be URLencoded.

TextEnabled no yesno


Enable/disable textoverlay.

yes = Enable textoverlay.no = Disable textoverlay.

13

Overlay API


3.5 ModifiersModifiers can be used to format file names, folders for uploaded images, notification messages, text in image overlays and similar. Amodifier always starts with a % or # character, followed by another character.

The percent (“%”) and hashtag (“#”) must be URL encoded. That means:

• % = %25

• # = %23

Example 5:Use image-%F-%H-%M-%S.jpg so timestamp uploaded video snapshots with the date, hour, minute and second the snapshotwas taken.

The following modifiers are available:

Date

Modifier Description Example

%c Date and time. Sun Dec 25 10:25:01 2011

%D Date in format MM/DD/YY. 25/12/2011

%F Date in format YYYY-MM-DD. 2011–12–25

%x Same as %D.

Time


%p AM or PM according to the given time or thecorresponding strings for the current locale. Noon istreated as PM and midnight as AM.

%r Time in a.m or p.m. notation. 10:25:01 AM

%R Time in 24–hour notation without seconds. 10:25

%T Time in 24–hour notation with seconds. 10:25:01

%X Same as %T.

%z Time zone as offset from UTC. +0000

%Z Time zone name or abbreviation. GMT

Year


%C The century as a 2–digit number (year/100). 20

%G The ISO 8601 week-numbering year as a 4–digitnumber.

2011

%g The ISO 8601 week-numbering year as a 2–digitnumber without the century, range 00 to 99.

11

%Y The Gregorian calendar year as a 4–digit number. 2011

%y The Gregorian calendar year as a 2–digit numberwithout the century, range 00 to 99.

11

14

Overlay API


Month


%b Abbreviated month name. Dec

%B Full month name. December

%h Same as %b.

%m Month as a 2–digit number, range 01 to 12. 12

Week


%U The week number as a 2–digit number, range 00 to 53.Sunday is the first day of the week. Week 01 is theweek starting with the first Sunday of the current year.

52

%V The ISO 8601 week number as a 2–digit number, range01 to 53. Monday is the first day of the week. Week01 is the first week that has at least four days in thecurrent year.

51

%W The week number as a 2–digit number, range 00 to 53.Monday is the first day of the week. Week 01 is theweek starting with the first Monday of the current year.

51

Day


%a Abbreviated weekday name. Sun

%A Full weekday name. Sunday

%d Day of the month as a 2–digit number, range 01 to 31. 25

%e Same as %d but a leading zero is replaced by a blankspace.

25

%j Day of the year as a 3–digit number, range 001 to 366. 359

%u Day of the week as an 1–digit number, range 1 to 7.Monday is 1.

7

%w Day of the week as an 1–digit number, range 0 to 6.Sunday is 0.

0

Hour


%H Hour in 24–hour fomat, range 00 to 23. 10

%I Hour in 12–hour format, range 01 to 12. 10

%k Same as %H but a leading zero is replaced by a blankspace.

%l Same as %I but a leading zero is replaced by a blankspace.

15

Overlay API


Minute


%M Minute as a 2–digit number, range 00 or 59. 25

Second


%f 1/100 seconds as a 2–digit number. 67

%s The number of seconds since EPOCH, that is, since1970–01–01 00:00:00 UTC.

1319178723

%S The current second as a 2–digit number, range 00 to 59. 10

Product and system information


#I The IP address. 10.13.24.88

#m The short MAC address (last 6 characters). 77:F8:26

#M The full MAC address (all characters). 00:40:8C:77:F8:26

#n The host name. axis-00408c77f826

#U<index> The fan status. <index> = A specified fan. For example1.

Stopped

#TC<ind-ex>

The temperature of the camera sensor in Celsius.<index> = A specified camera sensor. For example 1.

48,4

#TF<ind-ex>

The temperature of the camera sensor in Fahrenheit.index> = A specified camera sensor. For example 1.

119,1

Video information


#b Bit rate in kbit/s (no decimals). 16333

#B Bit rate in Mbit/s (two decimals). 16.33

#r Frame rate with two decimals. 30.00

#R Frame rate without decimals 30

#v Video source number 1

Pan/Tilt/Zoom information


#x Pan coordinate (signed, with two decimals). —77.61

#y Tilt coordinate (signed, with two decimals). —7.61

#z Zoom coordinate (range 1 to 19999). 256

#Z Zoom magnification (with one decimal). 12.0

#p Preset position number. If not at a preset position,blank space is used.

3

16

Overlay API


#P Preset name. If not at a preset position, blank space isused.

Door

#L OSDI (On Screen Directional Indicator) zone name. Azone within specified pan and tilt coordinates. If notwithin an OSDI zone, blank space is used.

Construction

Others


#s Sequence number of the video image as a 5–digitnumber.

#D Dynamic text overlay. See 3.6.2 Dynamic text overlay,on page 18.

%% The % character.

## The # character.

3.6 HTTP API

3.6.1 Text Overlay Arguments

A text overlay could be added to a specific video format. The following syntax could be used in the request:

• bitmap/image.bmp

• jpg/image.cgi

• mjpg/video.cgi

• media.amp

Access control: viewerMethod: GET

Syntax:

http://<servername>/axis-cgi/bitmap/image.bmp[?<argument>=<value<[&<argument>=<value>...]]

Syntax:

http://<servername>/axis-cgi/jpg/image.cgi[?<argument>=<value>[&<argument>=<value>...]]

Syntax:

http://<servername>/axis-cgi/mjpg/video.cgi[?<argument>=<value>[&<argument>=<value>...]]

Syntax:

rtsp://<servername>/axis-media/media.amp[?<parameter>=<value>[&<parameter>=<value>...]]

The following arguments and values can be used in JPEG, Motion JPEG, bitmap or RTSP CGI requests to edit text overlay.

17

Overlay API



clock=<int> 01

Show/hide the time stamp.

0 = Hide the time stamp1 = Show the time stamp.

date=<int> 01

Show/hide the date.

0 = Hide the date.1 = Show the date.

text=<int> 01

Enable/disable text overlay.

0 = Disable text overlay.1 = Enable text overlay.

textstring<string> A string The overlay text. The string must be URLencoded.

textcolor=string whiteblack

Text color.

white = White text color.black = Black text color.

textbackgroundcolor=<stri-ng>

blackwhitetransparentsemitransparent

Text background color.

black = Black text background color.white = White text background color.transparent = Transparent textbackground color.semitransparent =Semitransparent text backgroundcolor.

textpos=<string> topbottom

Position the text at top or bottom of theimage.

top = Position the text at top in theimage.bottom = Position the text at thebottom in the image.

3.6.2 Dynamic text overlay

Dynamic text overlay can be inserted in the text overlay. Since dynamic text is saved in the RAM memory only is removed on boot.

It is possible to use modifiers starting with % in this dynamic text. Modifiers starting with # can however not be used.

To use this functionality set Image.I#.Text.TextEnabled to yes and set Image.I#.Text.String to contain themodifier #D.

NoteThe ‘#’ in I# should be replaced by an integer starting from zero. The ‘#’ in #D is a modifier and should not be replaced.

Access control: operatorMethod: GET

18

Overlay API


Syntax:

http://<servername>/axis-cgi/dynamicoverlay.cgi?<argument>=<value>[&<argument>=<value>...]

With the following arguments and values:


action=<string> settextgettext

gettext = Get the dynamic textoverlay.settext = Set the dynamic textoverlay.

text=<string> A string The overlay text to apply, only applicablewith action=settext.

camera=<string>[,string,...]

1 (default) ...1 Selects the video channel. If omitted thedefault value camera=1 is used. Thisargument is only valid for Axis productswith more than one video channel. Thatis cameras with multiple view areasand video encoders with multiple videochannels.

1. Product/release-dependent. Check the product’s release notes.

19

Overlay API


4 Image Overlay API

4.1 DescriptionAn overlay image is a static image superimposed over the video image. An overlay can for example be used to provide extrainformation, for example a logotype.

The uploaded image must be in one of the following formats:

• Windows 24-bit BMP (full color).

• Windows 4-bit BMP (16 colors).

The size of the overlay image in pixels (width by height) must be exactly divisible by 4.

The maximum overlay image size supported is the same as the maximum image resolution.

4.2 Prerequisites


Property: Properties.API.HTTP.Version=3Firmware: 5.00 and later.

4.3 Common ExamplesEnable image overlay and place the image 10 pixels to the right and 900 pixels down from the top left corner.

http://myserver/axis-cgi/param.cgi?action=update&Image.I0.Overlay.Enabled=yes&Image.I0.Overlay.Xpos=10&Image.I0.Overlay.Ypos=900

4.4 Parameters

4.4.1 Image.I#.Overlay

To add an image overlay for all video formats the parameters in this group should be used.

NoteThe video stream needs to be restarted for parameter values to take affect.

[Image.I#.Overlay]


Enabled no yesno


Enable/disable overlayimage.The overlay im-age is stored in a filegiven by the parameterImage.OverlayP-ath.

yes = Enable overlayimage.no = Disable overlayimage.

20

Overlay API


[Image.I#.Overlay] (Continued)

XPos 0 An unsigned integer. admin: read, writeoperator: read, write

The overlays upper leftcorner is positioned atthis horizontal position(0 = to the left).

YPos 0 An unsigned integer. admin: read, writeoperator: read, write

The overlays upper leftcorner is positioned atthis horizontal position(0 = at the top).

4.4.2 Image

This group contains a parameter to specify the location of the image file used in image overlay.

[Image]


OverlayPath <string> admin: read, writeoperator: read, write

Specify the locationof the image used inimage overlay.

4.5 HTTP API

4.5.1 Image Overlay Arguments

An image overlay could be added to a specific video format. The following syntax could be used in the request:

• bitmap/image.bmp

• jpg/image.cgi

• mjpg/video.cgi

• media.amp

Access control: viewerMethod: GET

Syntax:

http://<servername>/axis-cgi/bitmap/image.bmp[?<argument>=<value<[&<argument>=<value>...]]

Syntax:

http://<servername>/axis-cgi/jpg/image.cgi[?<argument>=<value>[&<argument>=<value>...]]

Syntax:

http://<servername>/axis-cgi/mjpg/video.cgi[?<argument>=<value>[&<argument>=<value>...]]

21

Overlay API


Syntax:

rtsp://<servername>/axis-media/media.amp[?<parameter>=<value>[&<parameter>=<value>...]]

The following arguments and values can be used in JPEG, Motion JPEG, bitmap or RTSP CGI requests to add and edit text overlay.


overlayimage 01

Enable/disable overlay image. The overlayimage is stored in a file given by theparameter Image.OverlayPath.

0 = Disable overlay image.1 = Enable overlay image.

overlaypos=<int>,<int>overlaypos=<int>x<int>1

Two unsigned integers. The x and y coordinates defining theposition of the overlay image.

1. Obsolete.

4.5.2 Upload image

Images uploaded to the image overlay folder are processed by the CGI call_overlay_upload.cgi.

For action=upload the POST method must be used; the file content is provided in the HTTP body. The image file should beuploaded using Multipart/Form-Data as defined in RFC 1867.

Body:

POST /axis-cgi/call_overlay_upload.cgi?action=upload HTTP/1.0Content-Type: multipart/form-data; boundary=<boundary>Content-Length: <content length>

--<boundary>Content-Disposition: form-data; name="<name>";filename="<file name>"Content-Type: text/html

<file content>

--<boundary>

22

vapix overlay api - axis communications · pdf fileoverlayapi...

Documents