Face Log

Face Log takes an input video and generates a summary of all the unique people who appear in the video.

Main Scenario

Face Log is ideally used where you have a camera surveying a pinch-point where people pass through and you want to know who has walked past your camera and when. For example

  • Top of Escalators
  • Entrance/Lobby
  • Tunnel
  • Doorway

It is more complicated than the face-detector as it attempts to track the people as they walk through the scene and only report their appearance in the video once. It does this by using a tracker to combine close faces together, followed by a sighting generator which stitches similar tracks together.

digraph foo {
   rankdir = LR;
   node[shape=record, fontname="helvetica", fontsize="10", fontcolor="#ffffff", style="filled,rounded", fillcolor="#660066", color="#660066"];
   edge[fontname="helvetica", fontsize="10"];
   graph[fontname="helvetica", fontsize="10", fillcolor="red"];
   "input" -> "detect" [label="Frames"];
   "detect" -> "track" [label="Detections",weight="0.2"];
   "track" -> "output";
   "track" -> "sighting" [label="Tracks"];
   "sighting" -> "gender" [label="Sightings"];
   "sighting" -> "output";
   "gender" -> "output";
   input [label="Input\nVideo"];
   detect [label="Face\nDetector"];
   track [label="Tracker"];
   output [label="Face\nLog"];
   sighting [label="Sighting\nGenerator"];
   gender [label="Gender\nClassifier"];
   { rank = same; sighting; track; gender; }
}

The following are parameters which can be passed to the function, along with the video.

Parameter Description Values
max_frames Minimum size of detected faces (pixels) Minimum 0 (do all)
min_size Minimum size of detected faces (pixels) Minimum 30
gender Whether to classify gender of each sighting. False/True

Output

The output of a Face Log process includes

  • A link to a video which contains an overlay of detected tracks.
  • A link to an XML file which contains very detailed information about all the faces detected and which track in the video. - frame number - track number - face confidence

Optionally, you can also request the individual thumbnail images for each track.

Note, all links are only available for up-to 7 days after the job has finished.

Gender Detection

You can optionally request to detect the Gender of the identity for each sighting by specify the gender flag in the POST request.

Using Face Log

To use this service you have to upload a video or an image to the VideoAI.net server along with the parameters.

The face detector is capable of detecting faces down to approximately 30 pixels in width. The face detector will detect faces up to 30 degrees from frontal.

The speed of the final results depends on the input resolution of the video and its number of frames and whether you have specified the gender detector.

Request a Face Log

Request a face detection on the supplied video file.

POST /face_log
POST /face_log/ HTTP/1.1
Host: api.videoai.net
Authorization: Basic XXXXX

Example request for Face Log:

$ curl -L -H "Authorization: Basic XXXX" -F video=@somevideo.avi  http://api.videoai.net/face_log

Example response:

Content-Type: application/json
Content-Length: 214
Server: Werkzeug/0.10.4 Python/2.7.6
Date: Mon, 14 Sep 2015 14:18:53 GMT
{
  "status": "success",
  "task": {
    "analytic": "face_log",
    "complete": false,
    "job_id": "x5zYpM2DyigL3NyXRqicHX",
    "message": "In progress.",
    "start_time": "Mon, 14 Sep 2015 14:18:52 GMT"
  }
}

Check Job Status

Get the status of a face-log task

GET /face_log/(string: job_id)
GET /face_log/(string:job_id) HTTP/1.1
Host: api.videoai.net
Authorization: Basic XXXXX

Example request:

$ curl -L -H "Authorization: Basic XXXX" http://api.videoai.net/face_log/x5zYpM2DyigL3NyXRqicHX

Example response:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 7341
Server: Werkzeug/0.10.4 Python/2.7.6
Date: Mon, 14 Sep 2015 14:19:40 GMT
{
  "status": "success",
  "task": {
    "analytic": "face_log",
    "complete": true,
    "finish_time": "Mon, 14 Sep 2015 14:19:40 GMT",
    "frames": 150,
    "frames_processed": 150,
    "input_video": "tracking.mov",
    "job_id": "x5zYpM2DyigL3NyXRqicHX",
    "message": "Face log found 17 sightings, 28 tracks and 222 faces ",
    "number_of_sightings": 17,
    "resolution": "1920x1080@5.0fps",
    "results_video": "https://api.videoai.net/results/257/x5zYpM2DyigL3NyXRqicHX/face_log_x5zYpM2DyigL3NyXRqicHX.avi",
    "results_xml": "https://api.videoai.net/results/257/x5zYpM2DyigL3NyXRqicHX/face_log_x5zYpM2DyigL3NyXRqicHX.xml",
    "sightings": [
      {
        "confidence": 10.2170629501343,
        "end_frame": 18,
        "frames": 17,
        "gender": "",
        "gender_confidence": -1.0,
        "sighting_id": "5cb894a2-7547-475a-83e2-18fc6e0c0e60",
        "start_frame": 2,
        "thumbnail": "https://api.videoai.net/results/257/x5zYpM2DyigL3NyXRqicHX/thumbnail_5423140c-804f-4fe0-85a9-fd900aa4f0ee.jpg"
      },
      {
        "confidence": 1.74854040145874,
        "end_frame": 62,
        "frames": 39,
        "gender": "",
        "gender_confidence": -1.0,
        "sighting_id": "7ec368b4-1cf4-4bde-ae5c-4c3ebf5ed53a",
        "start_frame": 24,
        "thumbnail": "https://api.videoai.net/results/257/x5zYpM2DyigL3NyXRqicHX/thumbnail_7af53891-59ec-4db8-8ae6-a0ddb3c0bdb3.jpg"
      }, ...
    ]
  }
}

Job History

Get the status of the last 50 face-log jobs submitted.

GET /face_detect
GET /face_detect HTTP/1.1
Host: api.videoai.net
Authorization: Basic XXXXX

Example request:

$ curl -L -H "Authorization: Basic XXXX" http://api.videoai.net/face_detect

Example response:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 174071
Server: Werkzeug/0.10.4 Python/2.7.6
Date: Mon, 14 Sep 2015 14:26:29 GMT
{
  "status": "success",
  "tasks": [
    {
      "analytic": "face_log",
      "complete": true,
      "finish_time": "Mon, 14 Sep 2015 14:19:40 GMT",
      "frames": 150,
      "frames_processed": 150,
      "input_video": "tracking.mov",
      "job_id": "x5zYpM2DyigL3NyXRqicHX",
      "message": "Face log found 17 sightings, 28 tracks and 222 faces ",
      "number_of_sightings": 17,
      "resolution": "1920x1080@5.0fps",
      "results_video": "https://api.videoai.net/results/257/x5zYpM2DyigL3NyXRqicHX/face_log_x5zYpM2DyigL3NyXRqicHX.avi",
      "results_xml": "https://api.videoai.net/results/257/x5zYpM2DyigL3NyXRqicHX/face_log_x5zYpM2DyigL3NyXRqicHX.xml",
      "sightings": [
        // omitted for brevity
      ],
      "start_frame": 0,
      "start_time": "Mon, 14 Sep 2015 14:18:52 GMT",
      "success": true
    },
    {
      "analytic": "face_log",
      "complete": true,
      "finish_time": "Mon, 14 Sep 2015 14:18:45 GMT",
      "frames": 150,
      "frames_processed": 150,
      "input_video": "tracking.mov",
      "job_id": "yeSW4KPCE7pGi6GhMM9pd7",
      "message": "Face log found 17 sightings, 28 tracks and 222 faces ",
      "number_of_sightings": 17,
      "resolution": "1920x1080@5.0fps",
      "results_video": "https://api.videoai.net/results/257/yeSW4KPCE7pGi6GhMM9pd7/face_log_yeSW4KPCE7pGi6GhMM9pd7.avi",
      "results_xml": "https://api.videoai.net/results/257/yeSW4KPCE7pGi6GhMM9pd7/face_log_yeSW4KPCE7pGi6GhMM9pd7.xml",
      "sightings": [
        // omitted for brevity
      ],
      "start_frame": 0,
      "start_time": "Mon, 14 Sep 2015 14:18:03 GMT",
      "success": true
      }, ...
    }
  ]
}