Annotating Video

It is often helpful to annotate a video with additional data. It could be the license plate of a vehicle that drove by, the employee ID of the badge used to open a door, or the order information at a sales terminal. The Eagle Eye Networks Video API makes it easy to attach your data to a video stream.

Before starting with this API endpoint please reach out to api_support@een.com to be assigned a namespace. This helps prevents collisions with other applications.

Understanding the JSON payload

To create an annotation we accept the payload as a JSON structure. We will accept and store any valid JSON structure send to us. We do not index the contents of the payload and will return it if requested. Because we do not index the JSON data, you should store the UUID send back when an annotation is created. Using the UUID will speed up retrieval.

Understanding Bounding Boxes

Although we do not require a specific schema for the JSON payload, we do reserve keys that start with the _ character for internal system functionality. Please do not create your own variables starting with an underscore (_).

If you would like to display a bounding box over the preview images you can send it as shown in image on the left. This will draw a bounding box with the top left corner at 53% from the left edge and 33% from the top. The lower right corner of the box will be at 59% from the left edge and 44% from the top.

The actual bounding box coordinates are two nested arrays. The first is the coordiantes of the top left corner and the second is the coordinates of the lower right corner. Because a camera may display multiple streams in different aspect ratios, we use a ratio value instead of exact pixel values. The width should be calculated as the pixel value divided by the total width of the image. The height should be calculated as the pixel value divided by the total height of the image.

The bounding box is superimposed over the preview images and is not displayed when playing the video stream. we do not modify the video and maintain it exactly as we received it from the camera. If you would like to have the bounding box incorporated into the video you will need to modify the video and provide us the modified RTSP source.

Single Events vs Event Spans

New annotations are created as unique events and will automatically close after 10 seconds. The annootation can be updated with heartbeats to extend the length of the span but it will automatically close 10 seconds after the last hearbeat. If you have an exact end time for an annotation you may update the annotation to with a 'type' parameter set to 'end'.

I will be going into this topic in more detail in a future blog post.

Retriving Annotations

You can get an annotation by it's UUID or you can get a list of annotations.

You can use the UUID for the annotation that was returned when the annotation was created, or you can use the UUID returned for an entry when requesting a list of annotations. It is also possible to request a list of annotations limited to a set of UUIDs by using the 'exclusive' parameter.

Annotations are kept for the retention period of a camera. Because of this it is recommend that the data is also stored in another location if it is needed for longer than the retention periood of the caemra.

For retrieving an event span, the get list of events API endpoint provides additional information. It will provide all the updates and heartbeats for the event span. We will be covering this in more detail in a future blog post.

What else can we do with this?

Annotations are the first steps to pushing data into Eagle Eye Networks. This API opens up new categories of integrations that can be done. We already have select partners using this API and welcome the deeper integrations that it makes possible.

I hope you found this helpful. If you have any questions please feel free to reach out to us at api_support@een.com