Eagle Eye Networks

Annotation API

January 16, 2018 Eagle Eye Networks

Annotations API Demo-FI

Overview

In this project, we provide a referential Python script demonstrating the use of the Eagle Eye Networks (EEN) API to add GPS annotation data to a camera device’s timeline.   The script onlines the common steps to properly creating and updating new annotation objects.  Our goal is to prepare developers with the know-how to create and interact with any custom annotation data they may need for their particular application.

Before You Begin

You will need to collect a few items before we begin.

  1. EEN user account without two-factor authentication enabled since the demo code doesn’t support this feature.  
  2. ESN information for the camera to which you’d like to add annotations.
  3. EEN developer account and API key.  See https://developer.eagleeyenetworks.com/docs/getting-started for details.
  4. Install Docker. See link https://docs.docker.com/engine/installation/ for details.
  5. Install Git.  See https://git-scm.com/book/en/v2/Getting-Started-Installing-Git for details.
  6. Optionally, if you plan to add your own annotation types, you will need to provide a unique namespace identifier to the API.  Please email support to request a unique namespace for your data. Demo uses namespace 300 for GPS data.

Running the Demo

To make installing and running the demo easier, we created a Docker image containing all of the code and dependencies needed to make it work.  In this section, we walk you through the steps to download the code, build a Docker image, run a Docker container and execute the demo script.

Download the code from Github

Open a shell and run the following command to download the code to your local machine:

Build the Docker Image

Navigate into the annotation-api-demo folder. 

Run “docker build” to create the image.  We recommend tagging the image to make it easier to reference later.  You can do this with the -t option.

The Docker image is now ready for use in a container.  You can verify this by running the “docker images” command.  You should see gps-demo-image listed in the results.

Create and Run the Container

Use the “docker run” command to create a Docker container from the image.  Verify that the container is running properly with the “docker ps” command.  If all is well, you will see the “gps-demo” container listed in the output.   We use the –name option to give the container an easy name to remember.

Run the Python Demo Script

Use “docker exec” to open a bash shell in the container then verify the contents of the current folder (/code) by running the “ls” command.

You should see four files listed.

Filename Description
eenclient.py Simple Python API client.  Supports authentication, authorization and annotation endpoints.
gpsparse.py Python module with helper functions for parsing data from the GPS.txt file located in this project.
gps.py The main demo script showing how to add and update annotations using the EEN API.
gps.txt Text file containing GPS waypoints.

The primary script is named “gps.py”.  It contains the high level logic to create and update GPS annotation data using the EEN API.  You can run this script with the “-h” option to get a detailed description of the input arguments it accepts.  All positional arguments are required including your developer API key, username, password and camera ESN.

Try running the script using values from your account following the example below.  (Note: The start time is taken from the GPS.txt file if you don’t include one with the –start option.  The call will fail if start time falls outside of retention for the ESN.)

When using the “heartbeat” approach to updating an annotation, the first GPS coordinate is stored in the “start” attribute.  The remaining coordinates are added to the “_hb” attribute representing changes to the annotation over time.  You can clearly see this behavior in the logs above.

Now that you have seen how to run the demo, let’s walk through the code itself.

Source Code Walkthrough

We start off by authenticating and authorizing the user then fetching the device details to ensure everything is setup properly.  To interface with the EEN API, we use an instance of the EENClient class which provides methods to wrap all the logic required to build a proper API request.  The source code for this class is in the eenclient.py file.

Next, we initialize some variables and create an instance of TimeStepTacker to help us compute time intervals between GPS coordinate readings in the GPS.txt file.

To track timestamps for the annotation, we use the current_datetime_object object.  If you pass a starting timestamp on the command line then we set current_datetime_object to that value and the annotation will start at that time.  Otherwise, the starting timestamp will default to the timestamp for the first reading in the GPS.txt file.

The core of the script loops through the coordinates in the GPS.txt file.  For each new coordinate, we calculate the time elapsed since the previous reading, update the current_datetime_object and convert the date object into a string format consumable by the API.

We then read the next three lines in the file to parse out the GPS longitude, latitude, and velocity readings saving the results in the data dictionary.

Now we are ready to send coordinates to the API.  We use the uuid variable to track the unique identifier of the annotation we are creating.  The first time through the loop, this value will be None, so we create the annotation using the client.createAnnotation method.   On subsequent passes through the loop, we use the client.updateAnnotation method to update the annotation with the new coordinate values.

For the purposes of this demonstration, we set an arbitrary limit of five coordinates to the annotation.  After adding the fifth, we close the annotation using the client.updateAnnotation method with the update type set to ‘end’.

Lastly, we verify the annotation by reading it back with the client.getAnnotations method and printing the results to the console.

Conclusion

Our goal with this demonstration was to give you a real-world example of using the EEN API to add custom annotation data.  We hope the sample code gives you the information you need to add custom annotations to your particular application.   In summary, the main steps are to setup an API key, authenticate and authorize with your account credentials, obtain a namespace identifier for your data and make the create and update calls using the annotation API endpoints.

For additional information on the API, please checkout our documentation here:
https://developer.eagleeyenetworks.com.  You’ll find a detailed section on Annotations as well as many other aspects of the Eagle Eye platform.

Tags

Other posts that might interest you

loading

Our Video API: Getting Previews

This blog post is an example of how you can use the Eagle Eye Networks Video API to embed the preview stream on another site. This is a common request from…

May 27, 2014 Hans Kahler

Using Cloud to Avoid Traffic

Using cloud to avoid traffic?  How does that work? It's true, today I used cloud computing to avoid traffic.  Here's a little background.  At Eagle Eye, we not only are…

February 24, 2017 Hans Kahler

The Acceleration to Cloud Post COVID-19

https://vimeo.com/video/429369077 Due to COVID-19, many businesses are accelerating their shift to the cloud. This is especially true for video surveillance, where we’ve seen a significant increase in the demand for…

June 15, 2020 Eagle Eye Networks