IPS VideoAnalytics V3.21. Interface Description API for IPS Analytics Applications on the Axis ACAP Platform

Transcription

1 IPS VideAnalytics V3.21 Interface Descriptin API fr IPS Analytics Applicatins n the Axis ACAP Platfrm

2 Cpyright 2013 Securitn GmbH. IPS and the IPS lg are registered trademarks f Securitn GmbH. Securitn GmbH has included the infrmatin cntained in this manual t the best f its knwledge. Cntent f this dcumentatin exclusively serves infrmatin purpses and may be changed withut prir ntice. Securitn GmbH accepts n respnsibility fr damage r accidents, which ccur as a cnsequence f infrmatin, which has been given regarding devices r cmpnents nt manufactured by itself. Securitn GmbH accepts n respnsibility fr changes r mdificatins, which have nt been explicitly authrised by Securitn GmbH. Dcument Revisin: 06/03/13 R01 Securitn GmbH IPS Intelligent Vide Analytics Krnstadter Str. 4 D München Tel Fax [email protected]

3 Interface Descriptin API fr IPS Analytics Applicatins n the Axis ACAP Platfrm Cntents 1 Intrductin Functins Interfaces Cnfiguratin Interface C.1: Web cnfiguratr (IPS add-n) Interface C.2: Uplading cnfiguratin files (IPS add-n) Image verlays and metadata Interface IOM.1: SVG fr current image (IPS add-n) Interface IOM.2: SVG fr alarm image (IPS add-n) Interface IOM.3: SVG stream (IPS add-n) Interface IOM.4: Web viewer (IPS add-n) Event ntificatin Interface EN.1: TCP ntificatin (ACAP framewrk) Interface EN.2: HTTP request (ACAP framewrk) Interface EN.3: FTP uplad (ACAP framewrk) Interface EN.4: Output prt (ACAP framewrk) Interface EN.5: (ACAP framewrk) Interface EN.6: Extended TCP ntificatin (IPS add-n) Cntrl messages Interface CM.1: HTTP request (IPS add-n) Debug interface Interface DI.1: Syslg (ACAP framewrk) / 13 06/03/2013 V3.21 R01 A Business Unit f Securitn GmbH IPS

4 1 Intrductin This dcument is prvided as infrmatin fr third-party manufacturers f vide management systems, illustrating hw t cmmunicate with the IPS analytics applicatins fr the ACAP platfrm in rder t integrate them int large security infrastructures. Seamlessly integrating an analytics applicatin requires it t prvide a variety f functinality and interfaces. The ACAP platfrm cntains several interfaces fr this purpse and the IPS applicatins add further extensins. This dcument describes the interfaces added by IPS in detail. Als, it explains the ACAP interfaces rughly. There is mre detailed infrmatin n the Axis web site. 2 Functins The fllwing list indicates the functinality which is required t seamlessly integrate analytics applicatins embedded in cameras. It als indicates whether the ACAP framewrk prvides an interface fr implementing these functins. Where the ACAP framewrk des nt cntain a specific required interface, IPS prvides an add-n t implement the functin. Cnfiguratin ACAP framewrk: 0 interfaces IPS add-n: 2 interfaces Image verlays and metadata ACAP framewrk: 0 interfaces IPS add-n: 4 interfaces Event ntificatin ACAP framewrk: 5 interfaces IPS add-n: 1 interface Cntrl messages ACAP framewrk: 0 interfaces IPS add-n: 1 interface Debug interface ACAP framewrk: 1 interface IPS add-n: 0 interfaces 3 Interfaces One r mre interfaces are prvided t carry ut each f the abve functins. The interfaces are described belw. In this text, the term IPADDRESS refers t the IP address f the camera (e.g ) and APPNAME refers t the plain name f the IPS analytics applicatin: IPS-Intrusin: ipsintrusin IPS-Mtin: ipsmtin IPS-Sabtage: ipssabtage 4 / 13 06/03/2013 V3.21 R01 A Business Unit f Securitn GmbH IPS

5 3.1 Cnfiguratin Interface C.1: Web cnfiguratr (IPS add-n) IPS Intelligent Vide Analytics prvides a cnfiguratin tl t parameterise the analytics applicatin n the ACAP camera. This tl is a JavaScript applicatin that is included and installed with the EAP packet f the analytics applicatin. This s-called web cnfiguratr is started by entering the fllwing URL in the web brwser. T prvide mre in-depth integratin, third-party vide management systems can display and implement this JavaScript prgram via an integrated web cntrl. The web cnfiguratr enables simple and intuitive cnfiguratin f the analytics applicatin in a step-bystep sequence, cncluding by writing the cnfiguratin data t the camera and lading it int the analytics applicatin. Nte: The web cnfiguratr will be available in Q3/Q4 f Until that time, the analytics applicatin will be supplied with a cnfiguratin interface running under Silverlight. The Silverlight cnfiguratr may be called up by entering the fllwing URL: Interface C.2: Uplading cnfiguratin files (IPS add-n) If the cnfiguratin settings fr the analytics applicatin are available (three XML files and several ACAP parameter values), the third-party vide management system can uplad these data t the camera, in rder t cnfigure the analytics applicatin autmatically. Functins such as Backup and Restre can be implemented using this ptin. The cnfiguratin infrmatin cmprises three IPS cnfiguratin files and several ACAP parameters. Reading and writing the IPS cnfiguratin files is carried ut via the URLs listed belw. The ACAP parameters are nt prvided as files but in the frm f a data value, which is read and set separately via the http requests listed belw. URLs t read the IPS cnfiguratin files: URL t write the IPS cnfiguratin files: URL: Transmissin methd: POST Parameter in the POST request: realm=appname URL t read the ACAP parameters: URL t write the ACAP parameters: 5 / 13 06/03/2013 V3.21 R01 A Business Unit f Securitn GmbH IPS

6 In the fllwing statement, PARAMETERNAME represents the name f the parameter and VALUE specifies the value f the parameter: Finally, the cmmand UpdatePrgramming is sent t the analytics applicatin t relad the cnfiguratin, see Sectin Image verlays and metadata Interface IOM.1: SVG fr current image (IPS add-n) URL fr the verlays as SVG graphics f the current camera image: [?reslutin=widthxheight] [&reslutinsvg=widthxheight] [&reslutinimg=widthxheight] [&check_brwser=yes n] [&image=nne link link_jpeg link_mjpg embedded] [&metadata=nne shrt medium] [&perfdata=yes n] Parameters: reslutin=widthxheight: reslutinsvg=widthxheight: Specifies the width and height f the SVG. Default values: WIDTH: Original width f the camera image HEIGHT: Original height f the camera image Nte: Any pair f values (larger than 0) represents legal values fr this parameter. reslutinimg=widthxheight: Specifies the width and height f the image t which the SVG refers (i.e. links) r which the SVG embeds. Default values: WIDTH: Original width f the camera image HEIGHT: Original height f the camera image Nte: Legal values are nly the reslutins that the Axis camera ffers. These values can be inspected using this URL: Prperties.Image.Reslutin check_brwser=yes n: The server checks whether the brwser has the required functinality t display the results that are transmitted. Default=yes image=nne link link_jpeg link_mjpg embedded: The current camera image may be sent alng with the SVG graphic. link_jpeg incrprates a link t the current JPEG image, link_mjpg incrprates a link t the current MJPEG stream and embedded cpies the current JPEG camera image 6 / 13 06/03/2013 V3.21 R01 A Business Unit f Securitn GmbH IPS

7 (cded in Base64) int the SVG s XML tree. link incrprates either a link t the JPEG image r t the MJPEG stream, depending n whether a single frame r a stream is requested. Default=nne metadata=nne shrt medium: In additin t the verlays, further invisible infrmatin (metadata) is embedded in the SVG s XML tree. Its representatin within the SVG is described belw in mre detail. Default=nne perfdata=yes n: In additin t the verlays, further invisible runtime infrmatin abut vide analytics applicatin n the camera is embedded in the SVG s XML tree. Its representatin within the SVG is described belw in mre detail. Default=n Metadata: If metadata=shrt is specified, the SVG cntains additinal tags called MetaGlbal and MetaGlbalEntity. These cntain the fllwing parameters, whse values describe the current detectin status f the analytics applicatin. In any situatin, each f these parameters will appear nce. The parameter Alarm will appear several times, in case multiple alarms have been triggered. NameCamera: Gives the name f the camera. Value range: string NumberCamera: Gives the number f the camera. Value range: unsigned int TimeStamp: Gives the time f recrding the current camera image. This value is used t synchrnise the vide stream and the SVG stream. Value range: Datetime DetectinPrgram: Currently running prgram. Value range: 1 8 Day: Currently implemented day-night mde. Value range: true, false DetectinMde: Currently implemented detectin mde. Value range: active, inactive, revisin Activity: Indicates, if a specific activity is visible in the camera image. Value range: true, false Alarm: Indicates, if there is an alarm. In case there is n alarm present, this line will shw Nt alert. If multiple alerts have been raised, this line will appear multiple times. Pssible values: nne Alert_Detectin Alert_TestAlert Alert_VideFail Alert_VideAlert Alert_Technic Alert_Sabtage Alert_DataFail 7 / 13 06/03/2013 V3.21 R01 A Business Unit f Securitn GmbH IPS

8 Alert_CntrlDisp Alert_ItemRemved Alert_ItemLeft Alert_Fire Alert_Smke Alert_EmergencyLane PreAlert_Fire PreAlert_Smke Alert_3DZneDetectin Alert_Car Alert_Litering Alert_Reserve4 reserved fr future use. Alert_Reserve5 reserved fr future use. Cntdisp: Image checking mde fr visual inspectin f the camera image by human peratr is recmmended. Value range: true, false If metadata=medium is specified, the SVG cntains all tags frm mentined abve (metadata=shrt) and adds further attributes: MetaDisplayID and MetaSemanticType. These attributes are added t the graphical SVG verlays in rder t prvide further infrmatin. MetaDisplayID adds a unique identifier (int) t the SVG-rectangles that indicate tracked bjects. This allws t assciate image verlays f previus frames with image verlays f subsequent frames. MetaSemanticType refers t the type f bject that is illustrated with this SVG element. The fllwing list summarizes its pssible values. DetectinZne: The graphical element (plygn) illustrates the psitin and extent f a detectin zne specified via the cnfiguratin. DetectinZneImprtant: Same infrmatin as DetectinZne but it is imprtant t shw the zne, because smething serius happened (alarm). PreAlertObj_Current: PreAlertObj_Sleeping: AlertObj_Current: AlertObj_Sleeping: Object_Trace: Diagnse: Text: Nne: Refers t an bject that is tracked but did nt yet trigger an alarm. Refers t an bject that has been tracked and is nt visible r detectable any mre. It als did nt yet trigger an alarm. Indicates the bject that triggered alarm. This bject is still tracked by the applicatin. Indicates the bject that triggered alarm. This bject is nt detected by the applicatin any mre. Indicates the bjects mtin trajectry. Indicates the main text that is displayed t diagnse the applicatin. Sme further text that is displayed. The graphical bject has nt been assigned a semantic type. 8 / 13 06/03/2013 V3.21 R01 A Business Unit f Securitn GmbH IPS

9 Hidden: ZnePrivacy: Indicates that the graphical bject shuld nt be visualized but remain hidden. This is usually the case fr bjects that are intended fr debugging purpses. Indicates a plygn that has been cnfigured as zne whse cntent shuld nt be visible clearly but shuld permanently be bscured. ObscuredObject_Current: Indicates a rectangle arund a persn r sme ther mving bject that shuld nt be visible clearly but shuld be bscured. ObscuredFaceObj_Current: Indicates a rectangle arund a persn s face that shuld nt be visible clearly but shuld be bscured Perfdata: If perfdata=yes is specified, the SVG cntains additinal tags called PerfrmanceData and PerfrmanceEntity. These cntain the fllwing key-value pairs, wh describe the current runtime perfrmance f the vide analytics applicatin. fps: Returns the current frame rate f camera images that are currently prcessed by the analytics applicatin n the camera. Value range: duble SvgStreamCunt: Returns the number f SVG streams that are currently requested frm the analytics applicatin via the HTTP-requests. Value range: unsigned int Advantages: Images and verlays can be separated afterwards The request is very rapid, especially fr image=nne. SVG is accepted as a quasi-standard, e.g. directly cmpatible with Firefx withut plug-ins. Exact, frame-precise assignment f frame and verlays, if the frame and the verlays are laded tgether using image=embedded. Nte: In rder t achieve frame-precise assignment f the image and the verlays, sme srt f synchrnizatin has t be dne n the client side, where the metadata tag TimeStamp shuld be taken int accunt. Exceptin: The request with the embedded images (with image=embedded) directly delivers a synchrnized image at the same time via ne single request Interface IOM.2: SVG fr alarm image (IPS add-n) URL fr the verlays as an SVG graphic n the camera image during the mst recent alarm: [?reslutin=widthxheight] [&reslutinsvg=widthxheight] [&reslutinimg=widthxheight] 9 / 13 06/03/2013 V3.21 R01 A Business Unit f Securitn GmbH IPS

10 [&check_brwser=yes n] [&image=nne link link_jpeg link_mjpg embedded] [&metadata=nne shrt medium] [&perfdata=yes n] Parameters: The URL parameters are described in Sectin Definitin f metadata: The metadata are described in Sectin Advantages: Image and verlays can be separated afterwards. The request is very rapid, especially fr image=nne. SVG is accepted as a quasi-standard, e.g. directly cmpatible with Firefx withut plug-ins. Exact, frame-precise assignment f frame and verlays, if the frame and the verlays are laded tgether using image=embedded. Nte: Nte: If the parameter image is specified, the current camera image will be displayed, nt the alarm image Interface IOM.3: SVG stream (IPS add-n) URL fr the verlays as a http-multipart stream f SVG graphics: [?reslutin=widthxheight] [&reslutinsvg=widthxheight] [&reslutinimg=widthxheight] [&check_brwser=yes n] [&image=nne link link_jpeg link_mjpg embedded] [&metadata=nne shrt medium] [&perfdata=yes n] Parameters: The URL parameters are described in Sectin Definitin f metadata: The metadata are described in Sectin / 13 06/03/2013 V3.21 R01 A Business Unit f Securitn GmbH IPS

11 Advantages: Images and verlays can be separated afterwards. The stream is very rapid, especially fr image=nne. The stream is accepted as a quasi-standard, e.g. directly cmpatible with Firefx withut plug-ins. Exact, frame-precise assignment f frame and verlays, if the frame and the verlays are laded tgether using image=embedded. Nte: In rder t achieve frame-precise assignment f the image and the verlays, sme srt f synchrnizatin has t be dne n the client side, where the metadata tag TimeStamp shuld be taken int accunt. Exceptin: The request with the embedded images (with image=embedded) directly delivers a synchrnized image at the same time via ne single request Interface IOM.4: Web viewer (IPS add-n) The third party management system displays the web-page f the IPS Web Viewer in a web cntrl and executes JavaScript. URL: The third-party management system implements screen-recrding f the web cntrl and saves the images. Nte: The JavaScript applicatin requests tw streams, as described in Interface IOM.1 (Image and SVG) Advantages: Display is very rapid. Disadvantages: The images and verlays cannt be separated afterwards 3.3 Event ntificatin The ACAP framewrk prvides a little management functinality, including Event Ntificatin. In this, the analytics applicatin ntifies the ACAP framewrk, and this framewrk passes the ntificatin t the utside wrld in varius ways. The ACAP framewrk is highly cnfigurable, bth fr the user via the web-page and als fr external autmatin systems by using http requests Interface EN.1: TCP ntificatin (ACAP framewrk) Send user-cnfigurable texts via TCP t an IP address and prt Interface EN.2: HTTP request (ACAP framewrk) Send http requests with user-cnfigurable cntent t a URL Interface EN.3: FTP uplad (ACAP framewrk) The ACAP framewrk saves individual images t an FTP path, using a user-cnfigurable number 11 / 13 06/03/2013 V3.21 R01 A Business Unit f Securitn GmbH IPS

12 f individual frames befre and after the alarm event. The path, filename and file indices are all fully user-cnfigurable Interface EN.4: Output prt (ACAP framewrk) Activate utput prt: electrical utput n the rear f the camera Interface EN.5: (ACAP framewrk) Send an with user-cnfigurable subject and cntent t a list f addresses Interface EN.6: Extended TCP ntificatin (IPS add-n) An additinal interface is implemented fr signalling further events, using the same prcedure as fr Interface EN.1 but extending its functinality. TCP ntificatins are made fr the fur events listed belw. It is cnfigured by defining an IP address and a prt t which the TCP ntificatin is sent. The functin is activated by a further parameter. rt.appname.triggerremteaddress: Values: IP address rt.appname.triggerremteprt: Values: rt.appname.enabletriggeronactivityoralarm: Values: yes, n These parameters can be set either manually by the user via the brwser r autmatically via the fllwing http request. In this text string, IPADDRESS represents the address f the camera and PARAMETERNAME and PARAMETERVALUE represent the parameters named abve and their values. If ne f the fllwing fur events ccurs, the relevant string is sent t the pre-cnfigured IP address: Activity_Camera_CAMERANUMBER_Starts: Activity detected in the image Activity_Camera_CAMERANUMBER_Stps: End f the activity (activity switch-ff delay time included) Mtin_Camera_CAMERANUMBER_Trigger: Alarm has been triggered Mtin_Camera_CAMERANUMBER_Quit: Alarm has been acknwledged (autmatically r by the user) In the abve, CAMERANUMBER is a 3-digit number with leading zeres. 3.4 Cntrl messages An analytics applicatin is designed t run independently fr a very lng time and t analyse the camera image cntinuusly, utputting verlays and event ntificatins. In certain situatins, hwever, ccasinal interactin is required with external cmpnents r with the user. These interactins are mstly carried ut by means f cmmands Interface CM.1: HTTP request (IPS add-n) An http request t a pre-defined URL executes a cmmand that is specified in the request pa- 12 / 13 06/03/2013 V3.21 R01 A Business Unit f Securitn GmbH IPS

13 rameters. [&param=value] Fr this interface, a list f values fr COMMANDNAME is defined. QuitAlert NewTime_Day NewTime_Night ChangeDetectin_Active ChangeDetectin_Inactive ChangeDetectin_Revisin ChangeDetectPrg ResetDetectin ActivateTestAlert UpdatePrgramming Resets the alarm status f the analytics applicatin. Switches the analytics applicatin int Day mde. Switches the analytics applicatin int Night mde. Changes the status f the analytics applicatin t Active. Changes the status f the analytics applicatin t Inactive. Changes the status f the analytics applicatin t Revisin. Lads the cnfiguratin f a specified prgram, where the parameter number specifies a prgram number between 1 and 8, e.g.?cmmand=changedetectprg&number=1 Resets the analytics applicatin. Triggers an alarm in the analytics applicatin in rder t test the alarm respnse. Prmpts the analytics applicatin, t relad the cnfiguratin files. This is necessary if these files have been changed via the Web Cnfiguratr r via File Uplad. 3.5 Debug interface Interface DI.1: Syslg (ACAP framewrk) The debug reprt is written t the syslg f Linux. It can be viewed via the fllwing web-page: 13 / 13 06/03/2013 V3.21 R01 A Business Unit f Securitn GmbH IPS