Fence guard

The API consists of five methods:

• getConfiguration - Querying the complete ACAP configuration.

• setConfiguration - Upload a complete ACAP configuration file.

• getSupportedVersions - Get supported API versions.

• sendAlarmEvent - Send a stateful alarm event for VMS testing purposes.

• getConfigurationCapabilities - Get the boundaries and default values for the ACAP.

Software: EmbeddedDevelopment version 2.13 or higher is required for the ACAP to work.

Property: Properties.EmbeddedDevelopment.Version=2.13

In order to check if the ACAP is installed, use /axis-cgi/applications/list.cgi, which shows the status of all installed ACAP’s. It also lists the url to the configuration page and the license state of the ACAP.

1. Request the current configuration of the application:

[POST] http://myserver/local/fenceguard/control.cgi

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfiguration"
}

2. Parse the JSON response.

a. Success response example.

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfiguration",
  "data": {...}
}

b. Failure response example.

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfiguration",
  "error":
  {
    "code": XXXX,
    "message": "A descriptive error message."
  }
}

2. Validate current license state of the ACAP.

In order to post configurations to the ACAP, the license key must be valid.

[GET] http://myserver/axis-cgi/applications/list.cgi

3. Restore settings:

Post the configuration as params using the same JSON structure from data received from previous call.

[POST] http://myserver/local/fenceguard/control.cgi

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "setConfiguration",
  "params": {...}
}

1. Request the current configuration of the application:

[POST] http://myserver/local/fenceguard/control.cgi

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfiguration"
}

2. Parse the JSON response.

a. Success response example.

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfiguration",
  "data": {...}
}

b. Failure response example.

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfiguration",
  "error":
  {
    "code": XXXX,
    "message": "A descriptive error message."
  }
}

3. Parse the JSON Response:

The configuration JSON object is modified according to setConfiguration.

4. Validate current license state of the ACAP.

In order to post configurations to the ACAP the license key must be valid.

[GET] http://myserver/axis-cgi/applications/list.cgi

5. Upload new settings:

Post the configuration as params using the same JSON structure from data received from previous call.

[POST] http://myserver/local/fenceguard/control.cgi

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "setConfiguration",
  "params": {...}
}

a. Success response example.

{
  "apiVersion": "1.3",
  "context": "<client context>"
  "method": "setConfiguration",
  "data": {...}
}

b. Failure response example.

{
  "apiVersion": "1.3",
  "context": "<client context>"
  "method": "setConfiguration",
  "error":
  {
    "code": XXXX,
    "message": "A descriptive error message."
  }
}

Visualize alarming objects in live view and recorded video

Use this example to see all alarming objects in order to determine what causes alarms in both live view video, as well as in recorded video.

1. Configure with overlayResolution and alarmOverlayEnabled.

[POST] http://myserver/local/fenceguard/control.cgi

{
  "apiVersion": "1.3.",
  "context": "<client context>",
  "method": "setConfiguration",
  "params": {
    "cameras": [
      {
        "active": 
        "id": 1,
        "rotation": r,
        "overlayResolution": "1280x720"
      }
    ],
    "profiles": [
      {
        "name": "Profile 1",
        "alarmOverlayEnabled": true,
        ...
      }
    ]
  }
}

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "setCOnfiguration",
  "data": {...}
}

2. Validate in streams.

The video streams use the chosen resolution (e.g. 1280x720) and the specified rotation will have alarming objects with burnt in bounding boxes.

It is possible to request a video stream that ignores the alarm overlay despite using the chosen resolution. If the stream parameter overlays is set to either none or dynamic the overlay from the application is not shown.

rtsp://<IP-ADDRESS>/axis-media/media.amp?resolution=1280x720&overlays=off

1. Request the configuration capabilities of the application:

[POST] http://myserver/local/fenceguard/control.cgi

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfigurationCapabilities"
}

2. Parse the JSON response

a. Success response example.

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfigurationCapabilities",
  "data": {...}
}

b. Failure response example.

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfigurationCapabilities",
  "error":
  {
    "code": XXXX,
    "message": "A descriptive error message."
  }
}

The configuration JSON object is modified according to getConfigurationCapabilities.

Changes between apiVersion 1.2 and 1.3

Adds support for alarm overlays, which includes two new optional fields in the configuration of the application.

Request the current configuration of the ACAP.

Request

http://<servername>/local/fenceguard/control.cgi

Security level: Administrator

Method: POST

Request body syntax:

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfiguration"
}

Return value - Success

Returns the current configuration of the ACAP, in a JSON formatted response. In the following examples, the values w, h, t, x, y, p and r are numbers, the variable direction is a string with value “leftToRight”, “rightToLeft” or “both”. The directions left and right are defined from the perspective of a viewer that stands at the starting point of the segment, looking towards the end point of the same segment. The variable resolution is a string, e.g. “1280x720” or “640x360”. For a complete description of each field in the configuration, see Configuration parameter description.

HTTP Code: 200 OK

Content-Type: application/json

Response body syntax:

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfiguration",
  "data":
  {
    "cameras":
    [
      { "active": true, "id": 1, "rotation": r, "overlayResolution": resolution}
    ],
    "profiles":
    [
      {
        "name": "Profile 1",
        "uid": 1,
        "camera": 1,
        "alarmOverlayEnabled": true,
        "filters":
        [
          { "type": "sizePerspective", "data": [w,h], "active": true },
          { "type": "sizePercentage", "data": [w,h], "active": false },
          { "type": "timeShortLivedLimit", "data": t, "active": true }
        ],
        "triggers":[
          { "type": "fence", "data": [ [x,y], ..., [x,y] ] "alarmDirection": direction }
        ],
        "presets": [p],
        "perspective":
        [
          { "type": "bar", "data": [ [x,y], [x,y] ], "height": h},
          { "type": "bar", "data": [ [x,y], [x,y] ], "height": h},
          { "type": "bar", "data": [ [x,y], [x,y] ], "height": h}
        ]
      },
      { ... },
      { ... },
      { ... }
    ],
    "configurationStatus": 0
  }
}

The response if the camera supports multiple channels:

Channel specific properties are set in data.cameras. However, each profile has its individual settings, and refers to a camera id property with the data.profiles[j].camera property. The parameter “presets” is not present because it is only supported for mechanical PTZ-cameras.

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfiguration",
  "data":
  {
    "cameras":
    [
      { "active": true, "id": 1, "rotation": r, "overlayResolution": resolution1},
      { "active": false, "id": 2, "rotation": r, "overlayResolution": resolution2},
      { "active": false, "id": 3, "rotation": r, "overlayResolution": resolution3},
      { "active": false, "id": 4, "rotation": r, "overlayResolution": resolution4}
    ],
    "profiles":
    [
      {
        "name": "Profile 1",
        "uid": 1,
        "camera": 1,
        "alarmOverlayEnabled": true,
        "filters":
        [
          { "type": "sizePerspective", "data": [w,h], "active": true },
          { "type": "sizePercentage", "data": [w,h], "active": false },
          { "type": "timeShortLivedLimit", "data": t, "active": true }
        ],
        "triggers": [
          { "type": "fence", "data": [ [x,y], ..., [x,y] ] "alarmDirection": direction }
        ],

        "perspective":
        [
          { "type": "bar", "data": [ [x,y], [x,y] ], "height": h},
          { "type": "bar", "data": [ [x,y], [x,y] ], "height": h},
          { "type": "bar", "data": [ [x,y], [x,y] ], "height": h}
        ]
      },
      {
        "name": "Profile 2",
        "uid": 2,
        "camera": 3,
        "alarmOverlayEnabled": false,
        "filters": {...},
        "triggers": {...},
        "perspective": {...}
      },
      { ... },
      { ... },
      { ... }
    ],
    "configurationStatus": 0
  }
}

Return value - Error

Return value XXXX is a number.

HTTP Code: 200 OK

Content-Type: application/json

Response body syntax:

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfiguration",
  "error":
  {
    "code": XXXX
    "message": "A descriptive error message"
  }
}

Set the configuration of the ACAP. If the ACAP is not restarted beforehand, any ongoing events will be set as inactive when the new configuration is applied. This will cause ongoing recordings to stop. For multichannel products, all cameras are affected simultaneously.

There is a size limitation on POST transfer request which makes it suitable to send a minified JSON structure without white-spaces and new lines.

Modify specific properties

Below are some examples for how to change values, in the JSON file to perform specific actions. In the examples i is an index in the profile-array, not the uid of the profile.

Enable alarm overlay

In order to enable Alarm overlay for a profile, the resolution has to be specified for the camera in params.cameras[i].overlayResolution. Supported resolutions are listed by the getConfigurationCapabilities method. These resolutions will change if the capture mode in the camera is changed.

Each profile that is connected to that camera can then be specified to visualize its alarming objects in the video by activating the parameter params.profiles[i].alarmOverlayEnabled.

"cameras": [{
  "active": true,
  "id": 1,
  "rotation": r,
  "overlayResolution": "1280x720"
}],
"profiles": [{
  "name": "Profile 1",
  "camera": 1,
  "alarmOverlayEnabled": true
  ...
  }
]

Set image rotation

The image rotation for which the configuration is done should be specified in params.cameras[i].rotation. Valid values are (0, 90, 180, 270), which corresponds to the rotation of the camera.

Modify fence

To change the fence of a profile consisting of n connected straight lines connecting points [x0,y0], ..., [xn,yn] with alarm direction direction change the property params.profiles[i].triggers to

"triggers":[
  { "type": "fence", "data": [ [x0,y0], ..., [xn,yn] ], "alarmDirection": direction}
]

Modify size perspective filter

In order to apply a size perspective filter with two perspective bars with height and width defined as h1 [x11, y11], [x12,y12] and h2 [x21, y21], [x22,y22]. The first set of numbers are the start position, the second set of numbers are the end position. Both params.profiles[i].perspective and the size filter must be modified.

The perspective bars are added by changing params.profiles[i].perspective to

"perspective":
[
  { "type": "bar", "data": [ [x11,y11], [x12,y12] ], "height": h1},
  { "type": "bar", "data": [ [x21,y21], [x22,y22] ], "height": h2},
]

The size filter in params.profiles[i].filters should be modified to

"filters":
[
  { "type": "sizePerspective", "data": [w,h], "active": true },
  ...
]

The filter values width w and height h, and the heights of the perspective bars should be given in cm. Only one size filter can be active at any time, so sizePercentage must be disabled if sizePerspective is used. It is also crucial that the camera rotation is the same as the rotation specified in the configuration.

Set percentage filter

To apply a percentage filter with height h and width w in percent of image, params.profiles[i].filters should be modified to

"filters":
[
  { "type": "sizePercentage", "data": [w,h], "active": true },
]

Note that only one size filter can be active at any time, so sizePerspective must be disabled if sizePercentage is used. The width and height of an object follows the camera rotation, and the direction used will change if the rotation parameter is changed. That is, for a camera with a 640x360 resolution and a filter with width 10% and height 20%, then the corresponding box will have a size of 64x72 pixels if the camera rotation is 0 or 180 degrees. However, if the rotation is changed to 90 or 270 degrees, the same filter setting (width 10% and height 20%), corresponds to a box of 36x128 pixels.

Set short-lived object filter

In order to set the short-lived object filter value to t seconds params.profiles[i].filters should be modified to

"filters":
[
  { "type": "timeShortLivedLimit", "data": t, "active": true },
  ...
]

Modify presets

Note: Only for PTZ cameras. PTZ encoders are not supported.

To change the presets of a profile change the property params.profiles[i].presets to

"presets": [p]

where p is the id-number of the preset, the index value in the VAPIX-parameter PTZ.Preset.P0.Position.P<index>. The value can also be –1 for any-preset or –2 for anywhere.

Modify specific properties

Below are some examples for how to change values, in the JSON file to perform specific actions. In the examples i is an index in the profile-array, not the uid of the profile.

Request

http://<servername>/local/fenceguard/control.cgi

Security level: Administrator

Method: POST

Request body syntax:

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "setConfiguration",
  "params":
  {
    "cameras":
    [
      {"active": true, "id": 1, "rotation": r, "overlayResolution": resolution}
    ],
    "profiles":
    [
      {
        "name": "Profile 1",
        "uid": 1,
        "camera": 1,
        "alarmOverlayEnabled": true,
        "filters":
        [
          { "type": "sizePerspective", "data": [w,h], "active": true },
          { "type": "sizePercentage", "data": [w,h], "active": false },
          { "type": "timeShortLivedLimit", "data": t, "active": true }
        ],
        "triggers": [
          { "type": "fence", "data": [ [x,y], ..., [x,y] ], "alarmDirection": direction }
        ],
        "presets": [p],
        "perspective":
        [
          { "type": "bar", "data": [ [x,y], ..., [x,y] ],"height": h},
          { "type": "bar", "data": [ [x,y], ..., [x,y] ],"height": h},
          { "type": "bar", "data": [ [x,y], ..., [x,y] ],"height": h}
        ]
      },
      { ... },
      { ... },
      { ... }
    ]
  }
}

Return value - Success

HTTP Code: 200 OK

Content-Type: application/json

Response body syntax:

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "setConfiguration",
  "data": {}
}

Note that successful calls contains en empty data object.

Return value - Failure

Return value XXXX is a number.

HTTP Code: 200 OK

Content-Type: application/json

Response body syntax:

{
  "apiVersion": "1.3",
  "context":  "<client context>",
  "method": "setConfiguration",
  "error":
  {
    "code": XXXX,
    "message": "A descriptive error message"
  }
}

Request the boundaries and default values of the ACAP.

Request

http://<servername>/local/fenceguard/control.cgi

Security level: Administrator

Method: POST

Request body syntax:

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfigurationCapabilities"
}

Return value - Success

Return the boundaries and default values of the ACAP, in a JSON formatted response. This cgi will always return the same result for one camera independent of when it is called, i.e. these values cannot be changed through a cgi. However different cameras might return different result depending on their capabilities. In the following examples the values p, q, r and z are numbers. For a complete description of each field in the configuration see Configuration capabilities parameter description.

HTTP Code: 200 OK

Content-Type: application/json

Response body syntax:

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfigurationCapabilities",
  "data":
  {
    "alarmOverlay":{
      "isSupported": true,
      "cameras": [
        {"id": 1, "availableResolutions": ["1280x720", "640x360", ...]},
        {"id": 2, "availableResolutions": ["640x360", ...]}
      ]
      "maxNbrActiveCameras": 1
    },
    "filters":
    [
      {
        "type": "sizePercentage",
        "min": [width, height],
        "max": [width, height],
        "default": [width, height],
        "defaultActive": true
      },
      {
        "type": "timeShortLivedLimit",
        "min": p,
        "max": q,
        "default": r,
        "defaultActive": true
      }
    ],
    "triggers":
    [
      {
        "type": "fence",
        "min": [x,y],
        "max": [x,y],
        "minNbrVertices": p,
        "maxNbrVertices": q,
        "minNbrInstances": r,
        "maxNbrInstances": z,
        "validAlarmDirection": ["leftToRight", "rightToLeft", "both"],
        "defaultInstance": [ [x,y], [x,y], [x,y], [x,y] ],
        "defaultAlarmDirection": direction
      }
    ],
    "profiles":
    {
      "minNbrProfilesPerCamera": p,
      "maxNbrProfilesPerCamera": q,
      "minLengthName": r,
      "maxLengthName": z
    }
    "presets":
    {
      "maxNbrPresets": p,
      "defaultPreset": q
    }
  }
}

Return value - Error

Return value XXXX is a number.

HTTP Code: 200 OK

Content-Type: application/json

Response body syntax:

{
  "apiVersion": "1.3",
  "context": "<client context>",
  "method": "getConfigurationCapabilities",
  "error":
  {
    "code": XXXX,
    "message": A descriptive error message"
  }
}

Get a list of supported API versions for the ACAP (one for each major version).

Request

http://<servername>/local/fenceguard/control.cgi

Security level: Administrator

Method: POST

Request body syntax:

{
  "apiVersion": "1.3",
  "method": "getSupportedVersions",
  "context": "<client context>"
}

Return value - Success

HTTP Code: 200 OK

Content-Type: application/json

Response body syntax:

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

Return value - Failure

Return value XXXX is a number.

HTTP Code: 200 OK

Content-Type: application/json

Response body syntax:

{
  "apiVersion": "1.3",
  "method": "getSupportedVersions",
  "context": "<client context>",
  "error":
  {
    "code": XXXX,
    "message": "A descriptive error message"
  }
}

By using this method, it is possible to send a stateful alarm event for the specific profile <uid>. The stateful alarm event is active for a few seconds. The response message will be returned immediately. This can be used by VMS installers to check that the VMS configuration is correct (e.g. start recording). All events related to the profile will be sent.

Note: The profile will send events independent of its current state, i.e. in PTZ products, profiles that are connected to other than the current preset will also send events if triggered by the sendAlarmEvent method.

Request

http://<servername>/local/fenceguard/control.cgi

Security level: Operator

Method: POST

Request body syntax:

{
  "apiVersion": "1.3",
  "method": "sendAlarmEvent",
  "context": "<client context>",
  "params":
  {
    "profile": <uid>
  }
}

Return value - Success

HTTP Code: 200 OK

Content-Type: text/json

Response body syntax:

{
  "apiVersion": "1.3",
  "method": "sendAlarmEvent",
  "context": "<client context>",
  "data": {}
}

Return value - Failure

Return value XXXX is a number.

HTTP Code: 200 OK

Content-Type: text/json

Response body syntax:

{
  "apiVersion": "1.3",
  "method": "sendAlarmEvent",
  "context": "<client context>",
  "error":
  {
    "code": XXXX,
    "message": "A descriptive error message"
  }
}

The structure of a configuration object is the same in both the data object in the response for getConfiguration and the params object in the request for setConfiguration. The structure is the same for single and multichannel products, where the cameras objects should mirror the different VAPIX camera properties. The only difference appears when PTZ cameras are used, in which case the parameter preset can be optionally included.

Example configuration

The following example configuration will be described in details in table Parameter description table.

{
  "cameras":
  [
    { "active": bool, "id": 1, "rotation": r, "overlayResolution": resolution}
  ],
  "profiles":
  [
    {
      "name": "<client nice-name>",
      "uid": <uid>,
      "alarmOverlayEnabled": true,
      "camera": 1,
      "filters":
      [
        { "type": "sizePerspective", "data": [w,h], "active": true },
        { "type": "sizePercentage", "data": [w,h], "active": false },
        { "type": "timeShortLivedLimit", "data": t, "active": true }
      ],
      "triggers": [
        { "type": "fence", "data": [ [x,y], ..., [x,y] ], "alarmDirection": direction }
      ],
      "presets": [1],
      "perspective":
      [
        { "type": "bar", "data": [ [x,y], [x,y] ], "height": h},
        { "type": "bar", "data": [ [x,y], [x,y] ], "height": h}
      ]
    },
    { ... },
    { ... },
    { ... }
  ],
  "configurationStatus": 0
}

Parameter description table

Parameter presets description

Different apiVersion values for alarmOverlay parameters

The table below describe the parameters in the getConfigurationCapabilities.

AlarmOverlay

Filters

Triggers

Note: This section is only included in the configuration for mechanical PTZ cameras.

Note: No events are declared and the ACAP does not run if the license for the ACAP id invalid or missing.

Declaration of the Fence guard event

The declaration of the Fence guard event can be accessed through VAPIX and ONVIF event web service API:s.

The declaration of the Fence guard event as received from the VAPIX API:

<tnsaxis:CameraApplicationPlatform aev:NiceName="Applications">
  <FenceGuard aev:NiceName="Fence Guard">
    <CameraXProfileY wstop:topic="true" aev:NiceName="Fence Guard: <profile.name>">
      <aev:MessageInstance aev:isProperty="true">
        <aev:DataInstance>
          <aev:SimpleItemInstance Type="xsd:boolean" Name="active" aev:isPropertyState="true"/>
        </aev:DataInstance>
      </aev:MessageInstance>
    </CameraXProfileY>
  </FenceGuard>
</tnsaxis:CameraApplicationPlatform>

The event in this example is named CameraXProfileY, it is sent every time an object has crossed a specific fence In the alarm direction. It is based on a profile with camera=X and uid=Y. If it is a multichannel product the nicename attribute is changed to:

aev:NiceName="Fence Guard: <profile.name> (Image.I<profile.camera>.Name>)"

The name of the camera is taken from the parhand using the Image.I<index>.Name parameter. Value <index> is the same as the camera source value camera=X minus one.

The properties can be used for matching the criteria for triggering an action rule:

Property=<active> - Required. When an object crosses a fence direction the event is activated. It is inactivated after a short period of time.

<active> - A stateful event. An active event has the value “1”, and an inactive event has the value “0”.

Declaration of the Fence guard events for multichannel products

The following example shows how an event declaration will look for a scenario with a multichannel product with two cameras, and each camera has two profiles. The Namespaces and unnecessary tags has been removed for readability.

<TopicSet>
  <CameraApplicationPlatform>
    <FenceGuard NiceName="Fence Guard">
      <Camera1Profile1 topic="true" NiceName="Fence Guard: Garden Left (Camera 1)">
        <MessageInstance isProperty="true">
        <DataInstance>
        <SimpleItemInstance Type="xsd:boolean">
        </DataInstance>
        </MessageInstance>
      </Camera1Profile1>
      <Camera1Profile2 topic="true" NiceName="Fence Guard: Garden Right (Camera 1)">
        ...
      </Camera1Profile2>
      <Camera2Profile3 topic="true" NiceName="Fence Guard: Parking Day (Camera2)">
        ...
      </Camera2Profile3>
      <Camera2Profile4 topic="true" NiceName="Fence Guard: Parking Night (Camera 2)">
        ...
      </Camera2Profile4>
    </FenceGuard>
  </CameraApplicationPlatform>
  ...
</TopicSet>

CameraXProfileANY event

When the ACAP detects an object crossing a fence, it will be sent as an ANY event element for a specific camera.

The declaration of an ANY event as received from the VAPIX API:

<tnsaxis:CameraApplicationPlatform>
  <FenceGuard aev:NiceName="Fence Guard">
    <CameraXProfileANY wstop:topic="true" aev:NiceName="Fence Guard: Any Profile">
    .
    .
    .
    </CameraXProfileANY>
  </FenceGuard>
</tnsaxis:CameraApplicationPlatform>

The event in this example is named CameraXProfileANY and is sent every time an object has crossed a specific fence. It is based on a profile with camera=X. If it is a multichannel product the nicename attribute is changed to:

aev:NiceName="Fence Guard: Any Profile (<Image.I<profile.camera>.Name>)"

The name of the camera is taken from the parhand using the Image.I<index>.Name parameter. Value <index> is same as camera source value camera=X minus one.

CameraANY event

When the ACAP detects an object crossing a fence, it will be sent as a global ANY event element. A global ANY event is an ANY event for ANY camera, which means an alarm on any of the channels will also trigger this event.

The declaration of such ANY event as received from the VAPIX API:

<tnsaxis:CameraApplicationPlatform>
  <FenceGuard aev:NiceName="Fence Guard">
    <CameraANY wstop:topic="true" aev:NiceName="Fence Guard: Any Camera">
    .
    .
    .
    </CameraANY>
  </FenceGuard>
</tnsaxis:CameraApplicationPlatform>

The event stream

A client may subscribe to events from the VAPIX/ONVIF event stream. The format of the stream and its element are described in http://www.onvif.org/onvif/ver10/schema/onvif.xsd and http://www.onvif.org/onvif/ver10/topics/topicns.xml.

Using VAPIX, this stream can be retrieved over RTSP using the url:

rtsp://<servername>/axis-media/media.amp?event=on&eventtopic=axis:CameraApplicationPlatform/fenceguard/.

It is also possible to listen for a specific profile as below.

rtsp://<servername>/axis-media/media.amp?event=on&eventtopic=axis:CameraApplicationPlatform/FenceGuard/CameraXProfileY/.

CameraXProfileY

When the ACAP detects an object crossing a fence, it will be sent as an event element. An example of such an event is described below.

<tt:MetadataStream xmlns:tt="http://www.onvif.org/ver10/schema">
  <tt:Event xmlns:tt="http://www.onvif.org/ver10/schema">
    <wsnt:NotificationMessage xmlns:tns1="http://www.onvif.org/ver10/topics">
      <wsnt:ProducerReference>
        <wsa5:Address>uri://2a513b80-8211-4034-82e7-e8d48792c845/ProducerReference</wsa5:Address>
      </wsnt:ProducerReference>
      <wsnt:Message>
        <tt:Message UtcTime="2016-05-23T06:21:10.290542Z"PropertyOperation="Changed">
          <tt:Source/>
          <tt:Key/>
          <tt:Data>
            <tt:SimpleItem Name="active"Value="1"/>
          </tt:Data>
        </tt:Message>
      </wsnt:Message>
    </wsnt:NotificationMessage>
  </tt:Event>
</tt:MetadataStream>

The UtcTime of the message refers to the time of the event, i.e. this should be in sync with time stamps in an image stream with images of the actual physical event that took place.

Synchronize metadata with video stream

AXIS cameras uses the Real Time Streaming Protocol (RTSP) for controlling the media streaming between the camera and its clients. RTSP uses the Realtime Transport Protocol (RTP) for the packet format for the streaming of the meta/video data, and the RTP Control Protocol (RTCP) for the synchronization of the metadata and video data stream. The synchronization conversion from the absolute time (UTC timestamp) at the motion detection to the relative time (RTP timestamp) for the video stream, can be found in the RTCP packets.

Declaration of the MotionAlarm event

The declaration of the ONVIF Motion Alarm event can be accessed through the VAPIX and ONVIF event we service API:s. ONVIF event corresponds to CameraXProfileANY event. An ONVIF event will be sent if there is an ANY event being sent for a specific camera.

The declaration of the ONVIF Motion Alarm event as received from the VAPIX API:

<tns1:VideoSource>
  <MotionAlarm wstop:topic="true">
    <tt:MessageDescripion IsProperty="true">
      <tt:Source>
        <tt:SimpleItemDescription Name="Source" Type="tt:ReferenceToken"/>
      </tt:Source>
      <tt:Data>
        <tt:SimpleItemDescription Name="State" Type="xs:boolean"/>
      </tt:Data>
    </MessageDescription>
  </MotionAlarm>
</tns1:VideoSource>

The event stream

A client may subscribe to events from the VAPIX/ONVIF event stream. The format of the stream and its elements are described in  http://www.onvif.org/onvif/ver10/schema/onvif.xsd and http://www.onvif.org/onvif/ver10/topics/topicns.xml.

Using VAPIX, this stream can be retrieved over RTSP using:

rtsp://<servername>/axis-media/media.amp?event=on&eventtopic=onvif:VideoSource/MotionAlarm/.