The Accuware Sentinel CSV service is a service that provides for each camera:

1 – CSV files with location data

1.1 – Data structure

Data inside these CSV files are ordered by time-stamp and frame number (Columns 1 and 2).

Extract of a CSV file with 8 rows related to 8 people (Column 3) detected at the same time (Column 1) in the same frame (Column 2)

Where the fields are:

  • Column 1 – Timestamp – UNIX Epoch time stamp in milliseconds (see the info box below for details). Alternatively we can provide the number of milliseconds elapsed since the beginning of the video.
    • More information about the Unix epoch timestamp can be found in this page
    • More information about how to convert epoch to human readable date and vice versa can be found in this page
  • Column 2 – Frame number – every frame in a video stream is assigned a consecutive number. The frame number is shown inside the lower left corner of the processed video.
  • Column 3 – Person ID – this is an auto-generated number that identifies each pedestrian on the video. Please read the important information about the person ID contained inside this support page.
  • Column 4 – Position X – this is the X coordinate (in pixels) of the middle point between the 2 feet detected inside the frame.
  • Column 5 – Position Y – this is the Y coordinate (in pixels) of the middle point between the 2 feet detected inside the frame.
  • Columns 6 to 9 – represent the coordinates (in pixels) of the rectangle that encloses the person detected inside the frame (x, y, width, height). See image below.
  • Column 10 – do not consider. This field is used internally by Accuware for debug purposes.

Alternative positions

At a later stage we will make available a graphic tool inside the Accuware dashboard that allows you to calibrate the view of the camera against a floor plan using a calibration grid. Doing so it will be possible to retrieve the positions (fields 4 and 5):

  • as distance in meters of the person’s feet from the origin of the calibration grid.
  • or as WGS 84 coordinates (latitude and longitude).

The calibration will be a relatively simple process that won’t take more than 5 minutes per camera. The one below is an example of calibration grid. At present we are setting the calibration grid manually. In the image below, the origin of the grid (0,0) is the point in the bottom left corner. Based on the calibration grid it is easy to select region of interest on the floor. For example:

  • if you want to analyze the number of people that are walking in the right side of the aisle, you have to consider all the rows of the CSV file with Position X >= 1.25 meters.
  • if you want to analyze the number of people detected on the blue tile, you have to consider all the rows of the CSV file with 2.0 < Position X < 2.5 and  0 < Position Y < 0.5 (each square in the grid is 0.5 x 0.5 meters).

video_tracker_calibration_grid

1.2 – Download

The CSV files can be downloaded using the Accuware Sentinel dashboard or by calling an URL with the following structure:

Where:

  • Host: is the IP of the localhost (for local installations) or this URL s3.amazonaws.com/accuware.cv.sites (for cloud installations)
  • SiteID: is the ID of your site (provided by the Accuware Technical Support)
  • CameraID: is the ID of your camera (provided by the Accuware Technical Support)
  • YYYY: for digits for the year
  • MM: two digits for and the month
  • DD: two digits for the day
  • HH: two digits for the hour
  • mm: two digits for the minutes

1.3 – Availability

CSV files are generated every 5 minutes but there is approximately a 10 minute delay. So if it’s 12.30 PM, the time table will show data collected until 12.20 PM.

1.4 – Retention

Currently, the retention of the CSV files is unlimited. Anyway, since this might change in the near future, we suggest to download the CSV files on a regular base using a simple script, and store them in your local repository.

1.5 – Index file for each day

Each CSV file contains data for a time window of 5-minutes. In addition to these CSV files we provide also an index file with a list of all the 5-minutes segments recorded in a day. This index file can be downloaded by calling an URL with the following structure:

Where:

  • Host: is the IP of the localhost (for local installations) or this URL s3.amazonaws.com/accuware.cv.sites (for cloud installations)
  • SiteID: is the ID of your site (provided by the Accuware Technical Support)
  • CameraID: is the ID of your camera (provided by the Accuware Technical Support)
  • YYYY: for digits for the year
  • MM: two digits for and the month
  • DD: two digits for the day

The JSON returned will look like this:

Where the fields are:

  1. time – the identifier of the segment.
  2. video_in  – the file name of the original video.
  3. video_out – the file name of the processed video.
  4. detection_count – the total number of people detected inside the segment.
  5. frame_start – the starting frame of the segment.
  6. frame_end – the ending frame of the segment.

2 – CSV file with physical appearance data

Sentinel assigns a physical appearance encoded vector to each person detected. Each vector encodes the physical appearance of each one of the persons identified, including the colors of his clothes, his skin, height, hair, movements etc. The same person can have multiple encoding vectors assigned. A new vector is assigned to the same person, for example, if he/she leaves the field of view of a camera and re-enters again. All the encoding vectors for a specific video stream are contained in a single CSV file.

2.1 – Data structure

Data inside the CSV file are ordered by Person ID (starting from Person ID number 1). So row 1 is related to Person ID number 1, row 2 to Person ID number 2 and so on… Each row of the CSV file contains a vector of EXACTLY 128 numbers which represents the encoding of the physical appearance of a Person ID. Please be aware that the 128 numbers in each encoding vector don’t have any particular meaning when considered alone.

Example of CSV file with 12 encoding vectors related to Person IDs from 1 to 12.

The Person IDs we are referring to here, are the same Person IDs available inside the 3rd column of the CSV files with locations data:

How to use the encoding vectors?

The euclidean distance between 2 encoding vectors represents a similitude metric between the appearance of 2 Person IDs. The smaller the number resulting from the euclidean distance, the more similar the person are and so the higher is the probability that the 2 person IDs represent the same physical person.

To use practically the encoding vectors you have to consider 2 vectors of 128 numbers each and compute the euclidean distance using this standard formula:

where (p1,q1), (p2,q2), (p3,q3)…pn,qn (with n ranging from 1 to 128) are the n fields of each one of the 2 encoding vectors (P and Q) to be compared.

Example

This is an example of how to compute the euclidean distance on a CSV file made of 4 Person IDs (4 rows) each one made of (fake) encoding vectors of 3 numbers (instead of 128!):

The euclidean distance between Person ID 1 and 3 would be calculated like this:

    \[Euclidean Distance = \sqrt{(0.5 - -0.5)^2 + (0.3 - 0.7)^2 + (-0.1 - -0.1)^2}\]

Please keep in mind that this data is noisy by nature. So it could happen that:

  • the euclidean distance between 2 encoding vectors (2 person IDs) is low even if the 2 person IDs are related to 2 different persons. This can happen for example when the 2 persons are wearing clothes of similar colors.
  • the euclidean distance between 2 encoding vectors (2 person IDs) is high even if the 2 person IDs are related to the same person. This can happen for example when the same person is captured under different lighting conditions.

Again, you can find more info about the Person ID assignment topic inside this support page.

The euclidean distance is used by our Sentinel algorithm to make available the list of alike people inside the Sentinel dashboard as described inside this support page.

2.2 – Download and availability

The download link and the availability of the CSV files will be discussed on a case by case basis.

2.3 – Retention

Currently, the retention of the CSV files is unlimited. Anyway, since this might change in the near future, we suggest to download the CSV files on a regular base using a simple script, and store them in your local repository.