We use proprietary and third party's cookies to improve your experience and our services, identifying your Internet Browsing preferences on our website; develop analytic activities and display advertising based on your preferences. If you keep browsing, you accept its use. You can get more information on our Cookie Policy
Cookies Policy
Compressed Domain Video Analysis Open RESTful API Specification - FIWARE Forge Wiki

Compressed Domain Video Analysis Open RESTful API Specification

From FIWARE Forge Wiki

Jump to: navigation, search

Contents

Introduction to the Compressed Domain Video Analysis GE API

Please check the Legal Notice to understand the rights to use FI-WARE Open Specifications.

Compressed Domain Video Analysis GE API Core

The Compressed Domain Video Analysis GE API is a RESTful, resource-oriented API accessed via HTTP that uses XML-based representations for information interchange.

Intended Audience

This specification is intended for both software/application developers and application providers. This document provides a full specification of how to interoperate with platforms that implement Compressed Domain Video Analysis GE API.

In order to use these specifications, the reader should firstly have a general understanding of the appropriate Generic Enabler supporting the API (Compressed Domain Video Analysis GE Product Vision).

API Change History

This version of the Compressed Domain Video Analysis GE API Guide replaces and obsoletes all previous versions. The most recent changes are described in the table below:

Revision Date Changes Summary
May 2, 2012 Initial version
May 21, 2012
  • Adapted to new template
  • Added operations for multiple CDVA instances
August 21, 2012 Updated API operations
August 23, 2012 Changed GE name to Compressed Domain Video Analysis
November 8, 2012 Updated API operations according to new software version
April 26, 2013 Updated XML examples
May 23, 2013 Incorporated review comments
December 10, 2013
  • Updated API operations for new feature object tracking
  • Minor corrections
February 25, 2014
  • Updated XML examples
  • Added PBM notification

How to Read This Document

All FI-WARE RESTful API specifications will follow the same list of conventions and will support certain common aspects. Please check Common aspects in FI-WARE Open Restful API Specifications.

For a description of some terms used along this document, see the Compressed Domain Video Analysis GE Architecture Description.

The ONVIF specifications and the OASIS Web Services Notification standard define XML structures and elements that are used within the notification module of the Compressed Domain Video Analysis GE (see //{sinkNotificationURI}). The analyzed media is received by using RTP, as defined by RFC3550, and RTSP, as defined by RFC2326.

Additional Resources

You can download the most current version of this document from the FI-WARE API specification website: Compressed Domain Video Analysis Open RESTful API Specification. For more details about the Compressed Domain Video Analysis GE that this API is based upon, please refer to Compressed Domain Video Analysis GE Product Vision. Related documents, including an Architectural Description, are available at the same site.

General Compressed Domain Video Analysis GE API Information

Resources Summary

The resource summary is shown in the following overview.

Image:codoan_RESTful_API.png

Representation Format

The Compressed Domain Video Analysis GE API supports XML-based representation formats for both requests and responses. This is specified by setting the Content-Type header to application/xml, if the request/response has a body.

Resource Identification

The resource identification for HTTP transport is made using the mechanisms described by HTTP protocol specification as defined by RFC2616.

Links and References

Request forwarding is not supported in the current version of the Compressed Domain Video Analysis GE.

Limits

Limits are not yet specified for the current version of the Compressed Domain Video Analysis GE.

Versions

The current version of the used implementation of the Compressed Domain Video Analysis GE can be requested by the following HTTP request:

GET //{server}/{assetName}/version HTTP/1.1

Extensions

Querying extensions is not supported in the current version of the Compressed Domain Video Analysis GE.

Faults

Fault elements and their associated error codes are described in the following table.

Fault Element Error Code Reason Phrase Description Expected in All Requests?
GET, POST, PUT, DELETE 400 Bad Request The client sent an invalid request the server is not able to process. The message body may contain a detailed description of this error. [YES]
GET, POST, PUT, DELETE 404 Not Found The requested resource does not exist. The message body may contain a detailed description of this error. [YES]
GET, POST, PUT, DELETE 405 Method Not Allowed The used HTTP method is not allowed for the requested resource. The message body may contain a detailed description of this error. [YES]
GET, POST, PUT, DELETE 500 Internal Server Error An unforeseen error occurred at the server. The message body may contain a detailed description of this error. [YES]

API Operations

/version

Verb URI Description
GET //{server}/{assetName}/version getVersion: returns the current version of the Compressed Domain Video Analysis GE implementation

getVersion

Sample request:

GET //192.0.2.1/codoan/version HTTP/1.1
Accept: application/xml

Sample response:

HTTP/1.1 200 OK
Content-Length: 185
Content-Type: application/xml
Server: codoan REST server

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Version>2.0.0</Version>
  <Copyright>(c) 2010-2014 Imaging and Computer Vision, Siemens Corporate Technology</Copyright>
</Codoan>

On success, the response code to this request is as stated in the example above. In case an error occurred, one of the error codes described in section Faults is returned.

/instances

Verb URI Description
GET //{server}/{assetName}/instances listInstances: lists all active instances of the Compressed Domain Video Analysis GE
POST //{server}/{assetName}/instances createInstances: creates a new instance of the Compressed Domain Video Analysis GE

listInstances

Sample request:

GET //192.0.2.1/codoan/instances HTTP/1.1
Accept: application/xml

Sample response:

HTTP/1.1 200 OK
Content-Length: 407
Content-Type: application/xml
Server: codoan REST server

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance activeSinks="0" detectEvents="true" detectObjects="true" trackObjects="true" id="101" isRunning="false" streamURI="rtsp://192.0.2.2/stream1"/>
    <Instance activeSinks="3" detectEvents="true" detectObjects="false" trackObjects="false" id="102" isRunning="true" streamURI="rtsp://192.0.2.8/camera7"/>
  </Instances>
</Codoan>

createInstance

Sample request:

POST //192.0.2.1/codoan/instances HTTP/1.1
Accept: application/xml
Content-Length: 205
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance detectEvents="true" detectObjects="true" trackObjects="true" streamURI="rtsp://192.0.2.2/stream1"/>
  </Instances>
</Codoan>

Sample response:

HTTP/1.1 201 Created
Content-Length: 248
Content-Type: application/xml
Server: codoan REST server

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance activeSinks="0" detectEvents="true" detectObjects="true" trackObjects="true" id="101" isRunning="false" streamURI="rtsp://192.0.2.2/stream1"/>
  </Instances>
</Codoan>

On success, the response codes to these requests are as stated in the examples above. In case an error occurred, one of the error codes described in section Faults is returned.

/{instanceID}

Verb URI Description
GET //{server}/{assetName}/instances/{instanceID} getInstanceInfo: returns information about an existing instance of the Compressed Domain Video Analysis GE
DELETE //{server}/{assetName}/instances/{instanceID} destroyInstance: destroys an existing instance of the Compressed Domain Video Analysis GE
PUT //{server}/{assetName}/instances/{instanceID}?action=start startInstance: starts the analysis of an existing instance of the Compressed Domain Video Analysis GE
PUT //{server}/{assetName}/instances/{instanceID}?action=stop stopInstance: stops the analysis of an existing instance of the Compressed Domain Video Analysis GE

getInstanceInfo

Sample request:

GET //192.0.2.1/codoan/instances/101 HTTP/1.1
Accept: application/xml

Sample response:

HTTP/1.1 200 OK
Content-Length: 248
Content-Type: application/xml
Server: codoan REST server

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance activeSinks="0" detectEvents="true" detectObjects="true" trackObjects="true" id="101" isRunning="false" streamURI="rtsp://192.0.2.2/stream1"/>
  </Instances>
</Codoan>

destroyInstance

Sample request:

DELETE //192.0.2.1/codoan/instances/101 HTTP/1.1
Accept: application/xml

Sample response:

HTTP/1.1 200 OK
Content-Length: 248
Content-Type: application/xml
Server: codoan REST server

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance activeSinks="0" detectEvents="true" detectObjects="true" trackObjects="true" id="101" isRunning="false" streamURI="rtsp://192.0.2.2/stream1"/>
  </Instances>
</Codoan>

startInstance

Sample request:

PUT //192.0.2.1/codoan/instances/101?action=start HTTP/1.1
Accept: application/xml

Sample response:

HTTP/1.1 200 OK
Content-Length: 247
Content-Type: application/xml
Server: codoan REST server

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance activeSinks="1" detectEvents="true" detectObjects="true" trackObjects="true" id="101" isRunning="true" streamURI="rtsp://192.0.2.2/stream1"/>
  </Instances>
</Codoan>

stopInstance

Sample request:

PUT //192.0.2.1/codoan/instances/101?action=stop HTTP/1.1
Accept: application/xml

Sample response:

HTTP/1.1 200 OK
Content-Length: 248
Content-Type: application/xml
Server: codoan REST server

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance activeSinks="0" detectEvents="true" detectObjects="true" trackObjects="true" id="101" isRunning="false" streamURI="rtsp://192.0.2.2/stream1"/>
  </Instances>
</Codoan>

On success, the response codes to these requests are as stated in the examples above. In case an error occurred, one of the error codes described in section Faults is returned.

/config

Verb URI Description
GET //{server}/{assetName}/instances/{instanceID}/config getInstanceConfig: returns the configuration of an existing instance of the Compressed Domain Video Analysis GE
PUT //{server}/{assetName}/instances/{instanceID}/config configureInstance: configures an existing instance of the Compressed Domain Video Analysis GE


The following parameters can be set to configure an instance:

  • Event (Change) Detection
    • NumberOfTrainingFrames
      • The number of initial frames that should be used to train the algorithm
      • Default: 4 * SlidingWindowSize
      • Type: Positive integer
    • SlidingWindowSize
      • The size (in number of frames) of two sliding windows to calculate ANORP and ARPS factors
      • Default: 10
      • Type: Positive integer
    • ThresholdANORPFactor
      • Calculated ANORP factors are compared to this threshold
      • Default: 1.2
      • Type: Non-negative decimal
    • ThresholdARPSFactor
      • Calculated ARPS factors are compared to this threshold
      • Default: 1.75
      • Type: Non-negative decimal
    • ThresholdIFrame
      • Threshold for detecting I-frames within a video stream
      • Default: 5
      • Type: Non-negative decimal
  • Moving Object/Person Detection
    • type
      • The type of objects that will be detected
      • Default: "Other"
      • Type: "Other" or "Person"
    • BoxFilterSize
      • Size of a post-processing box filter applied to blocks of pixels
      • Default: 3
      • Type: Odd positive integer
    • ThresholdH264MOC
      • Threshold for detecting moving blocks within frames
      • Default: 6
      • Type: Positive integer
    • NumberOfPreviousFrames
      • The number of previous frames to be considered during temporal filtering
      • Default: 3
      • Type: Non-negative integer
    • NumberOfSubsequentFrames
      • The number of subsequent frames to be considered during temporal filtering
      • Default: 3
      • Type: Non-negative integer
    • DistanceWeight
      • Weight for neighboring frames during temporal filtering
      • Default: 1.0
      • Type: Non-negative decimal
    • FilterStrength
      • The strength of the temporal filtering process
      • Default: 0.5
      • Type: Non-negative decimal less than 1.0
  • Object Tracking
    • UseMovingObjectHistory
      • If set to true, the analyzer stores detected objects in an object history, which is then used for tracking objects. If set to false, objects are tracked by considering previous frames only.
      • Default: true
      • Type: Boolean
    • BoundingBoxOverlapLimit
      • The lower limit for a positive match of two bounding boxes
      • Default: 0.25
      • Type: Non-negative decimal greater than 0.0 and less than or equal 1.0 (indicates percent)

For a more detailed description, please refer to the respective reference in the Compressed Domain Video Analysis Open Specification.

getInstanceConfig

Sample request:

GET //192.0.2.1/codoan/instances/101/config HTTP/1.1
Accept: application/xml

Sample response:

HTTP/1.1 200 OK
Content-Length: 1344
Content-Type: application/xml
Server: codoan REST server

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance activeSinks="0" detectEvents="true" detectObjects="true" trackObjects="true" id="101" isRunning="false" streamURI="rtsp://192.0.2.2/stream1">
      <Configuration>
        <EventDetection type="GlobalChange">
          <NumberOfTrainingFrames>40</NumberOfTrainingFrames>
          <SlidingWindowSize>10</SlidingWindowSize>
          <ThresholdANORPFactor>1.2</ThresholdANORPFactor>
          <ThresholdARPSFactor>1.75</ThresholdARPSFactor>
          <ThresholdIFrame>5</ThresholdIFrame>
        </EventDetection>
        <ObjectDetection type="Person">
          <ThresholdH264MOC>6</ThresholdH264MOC>
          <BoxFilterSize>3</BoxFilterSize>
          <TemporalFilter>
            <NumberOfPreviousFrames>3</NumberOfPreviousFrames>
            <NumberOfSubsequentFrames>3</NumberOfSubsequentFrames>
            <DistanceWeight>1.0</DistanceWeight>
            <FilterStrength>0.5</FilterStrength>
          </TemporalFilter>
        </ObjectDetection>
        <ObjectTracking>
          <UseMovingObjectHistory>true</UseMovingObjectHistory>
          <BoundingBoxOverlapLimit>0.25</BoundingBoxOverlapLimit>
        </ObjectTracking>
      </Configuration>
    </Instance>
  </Instances>
</Codoan>

configureInstance

Sample request:

PUT //192.0.2.1/codoan/instances/101/config HTTP/1.1
Accept: application/xml
Content-Length: 946
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance detectEvents="false" detectObjects="true" trackObjects="true" streamURI="rtsp://192.0.2.2/stream1">
      <Configuration>
        <ObjectDetection type="Person">
          <ThresholdH264MOC>6</ThresholdH264MOC>
          <BoxFilterSize>3</BoxFilterSize>
          <TemporalFilter>
            <NumberOfPreviousFrames>3</NumberOfPreviousFrames>
            <NumberOfSubsequentFrames>3</NumberOfSubsequentFrames>
            <DistanceWeight>1.0</DistanceWeight>
            <FilterStrength>0.5</FilterStrength>
          </TemporalFilter>
        </ObjectDetection>
        <ObjectTracking>
          <UseMovingObjectHistory>true</UseMovingObjectHistory>
          <BoundingBoxOverlapLimit>0.25</BoundingBoxOverlapLimit>
        </ObjectTracking>
      </Configuration>
    </Instance>
  </Instances>
</Codoan>

Sample response:

HTTP/1.1 200 OK
Content-Length: 989
Content-Type: application/xml
Server: codoan REST server

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance activeSinks="0" detectEvents="false" detectObjects="true" trackObjects="true" id="101" isRunning="false" streamURI="rtsp://192.0.2.2/stream1">
      <Configuration>
        <ObjectDetection type="Person">
          <ThresholdH264MOC>6</ThresholdH264MOC>
          <BoxFilterSize>3</BoxFilterSize>
          <TemporalFilter>
            <NumberOfPreviousFrames>3</NumberOfPreviousFrames>
            <NumberOfSubsequentFrames>3</NumberOfSubsequentFrames>
            <DistanceWeight>1.0</DistanceWeight>
            <FilterStrength>0.5</FilterStrength>
          </TemporalFilter>
        </ObjectDetection>
        <ObjectTracking>
          <UseMovingObjectHistory>true</UseMovingObjectHistory>
          <BoundingBoxOverlapLimit>0.25</BoundingBoxOverlapLimit>
        </ObjectTracking>
      </Configuration>
    </Instance>
  </Instances>
</Codoan>

On success, the response codes to these requests are as stated in the examples above. In case an error occurred, one of the error codes described in section Faults is returned.

/sinks

Verb URI Description
GET //{server}/{assetName}/instances/{instanceID}/sinks listSinks: lists all active sinks of an existing instance of the Compressed Domain Video Analysis GE
POST //{server}/{assetName}/instances/{instanceID}/sinks addSink: adds a new sink to an existing instance of the Compressed Domain Video Analysis GE

listSinks

Sample request:

GET //192.0.2.1/codoan/instances/101/sinks HTTP/1.1
Accept: application/xml

Sample response:

HTTP/1.1 200 OK
Content-Length: 280
Content-Type: application/xml
Server: codoan REST server

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance activeSinks="0" detectEvents="true" detectObjects="true" trackObjects="true" id="101" isRunning="false" streamURI="rtsp://192.0.2.2/stream1">
      <Sinks/>
    </Instance>
  </Instances>
</Codoan>

addSink

Sample request:

POST //192.0.2.1/codoan/instances/101/sinks HTTP/1.1
Accept: application/xml
Content-Length: 329
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance detectEvents="true" detectObjects="true" trackObjects="true" streamURI="rtsp://192.0.2.2/stream1">
      <Sinks>
        <Sink sinkNotificationURI="http://192.0.2.3/notification/stream1" sendXml="true" sendBinaryMap="true"/>
      </Sinks>
    </Instance>
  </Instances>
</Codoan>

Sample response:

HTTP/1.1 201 Created
Content-Length: 381
Content-Type: application/xml
Server: codoan REST server

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance activeSinks="1" detectEvents="true" detectObjects="true" trackObjects="true" id="101" isRunning="false" streamURI="rtsp://192.0.2.2/stream1">
      <Sinks>
        <Sink id="201" sinkNotificationURI="http://192.0.2.3/notification/stream1" sendXml="true" sendBinaryMap="true"/>
      </Sinks>
    </Instance>
  </Instances>
</Codoan>

On success, the response codes to these requests are as stated in the examples above. In case an error occurred, one of the error codes described in section Faults is returned.

/{sinkID}

Verb URI Description
GET //{server}/{assetName}/instances/{instanceID}/sinks/{sinkID} getSinkInfo: returns information about of an existing sink of the Compressed Domain Video Analysis GE
DELETE //{server}/{assetName}/instances/{instanceID}/sinks/{sinkID} removeSink: Removes an existing sink of the Compressed Domain Video Analysis GE

getSinkInfo

Sample request:

GET //192.0.2.1/codoan/instances/101/sinks/201 HTTP/1.1
Accept: application/xml

Sample response:

HTTP/1.1 200 OK
Content-Length: 381
Content-Type: application/xml
Server: codoan REST server

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance activeSinks="1" detectEvents="true" detectObjects="true" trackObjects="true" id="101" isRunning="false" streamURI="rtsp://192.0.2.2/stream1">
      <Sinks>
        <Sink id="201" sinkNotificationURI="http://192.0.2.3/notification/stream1" sendXml="true" sendBinaryMap="true"/>
      </Sinks>
    </Instance>
  </Instances>
</Codoan>

removeSink

Sample request:

DELETE //192.0.2.1/codoan/instances/101/sinks/201 HTTP/1.1
Accept: application/xml

Sample response:

HTTP/1.1 200 OK
Content-Length: 381
Content-Type: application/xml
Server: codoan REST server

<?xml version="1.0" encoding="UTF-8"?>
<Codoan>
  <Instances>
    <Instance activeSinks="0" detectEvents="true" detectObjects="true" trackObjects="true" id="101" isRunning="false" streamURI="rtsp://192.0.2.2/stream1">
      <Sinks>
        <Sink id="201" sinkNotificationURI="http://192.0.2.3/notification/stream1" sendXml="true" sendBinaryMap="true"/>
      </Sinks>
    </Instance>
  </Instances>
</Codoan>

On success, the response codes to these requests are as stated in the examples above. In case an error occurred, one of the error codes described in section Faults is returned.

//{sinkNotificationURI}

Verb URI Description
POST //{sinkNotificationURI} notifySink: notifies the sink in case of events or detected objects

notifySink

The notification is sent via a POST request. The data in its body either represents an XML structure or a Portable Bitmap (PBM). Thereby, the parameters sendXml and sendBinaryMap, which are set in the addSink operation, indicate if an XML and/or a PBM structure should be sent, respectively.

XML sample request:

POST //192.0.2.3/notification/stream1 HTTP/1.1
User-Agent: codoan REST client
Content-Length: 1795
Content-Type: application/xml

<?xml version="1.0" encoding="UTF-8"?>
<MetadataStream xmlns="http://www.onvif.org/ver10/schema"
               xmlns:wsn="http://docs.oasis-open.org/wsn/b-2"
               xmlns:codoan="http://www.fi-ware.eu/data/cdva/codoan/schema"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:schemaLocation="http://www.fi-ware.eu/data/cdva/codoan/schema http://cdvideo.testbed.fi-ware.eu/codoan/schema/codoan_onvif.xsd">

 <Event>
   <wsn:NotificationMessage>
     <wsn:Message>
       <codoan:EventDescription>
         <codoan:EventType>GlobalChange</codoan:EventType>
         <codoan:FrameNumber>100</codoan:FrameNumber>
       </codoan:EventDescription>
     </wsn:Message>
   </wsn:NotificationMessage>
 </Event>

 <VideoAnalytics>
   <Frame UtcTime="2012-05-10T18:12:05.432Z" codoan:FrameNumber="100">
     <Object ObjectId="0">
       <Appearance>
         <Shape>
           <BoundingBox bottom="15.0" top="5.0" right="25.0" left="15.0"/>
           <CenterOfGravity x="20.0" y="10.0"/>
         </Shape>
       </Appearance>
     </Object>
     <Object ObjectId="1">
       <Appearance>
         <Shape>
           <BoundingBox bottom="25.0" top="15.0" right="35.0" left="25.0"/>
           <CenterOfGravity x="30.0" y="20.0"/>
         </Shape>
       </Appearance>
     </Object>
   </Frame>
 </VideoAnalytics>

 <Extension>
   <codoan:StreamProperties>
     <codoan:StreamUri>rtsp://camera/stream1</codoan:StreamUri>
     <codoan:GopSize>10</codoan:GopSize>
     <codoan:FrameRate>25.0</codoan:FrameRate>
     <codoan:FrameWidth>352</codoan:FrameWidth>
     <codoan:FrameHeight>288</codoan:FrameHeight>
   </codoan:StreamProperties>
 </Extension>
</MetadataStream>

PBM sample request:

POST //192.0.2.3/notification/stream1 HTTP/1.1
User-Agent: codoan REST client
Content-Length: 12761
Content-Type: image/x-portable-bitmap

P4
# created by Codoan
# analyzed media: rtsp://192.0.2.2/stream1
# frame number: 100
352 288
<binary data>

Assumed response:

HTTP/1.1 200 OK
Personal tools
Create a book