*******************************************************************************
* REVISIONS:
*
* v1.0 (04/09/2008)
*   First version.
*
* v2.0 (09/10/2008)
*   Updated to account for new input file structure, following feedback during
*   meeting at Surrey.
*
* v2.1 (23/10/2008)
*   Updated so that "ALL" in a challenge field is replaced with the actual IDs
*   of the challengers. Also updated to ensure that all directories now end with
*   a backslash (note that examples have been updated accordingly).
*
*******************************************************************************

mobio_parser.h contains classes and functions to read and write data
to be used to pass information between command line tools in the
mobio project.


All three tasks (detection, feature localization and authentication) use
a common mobio_inputfile object that defines:
- input/output directories
- file extension of the input files (so that both video and audio can be tested)
- IDs of the participants to be enrolled (with corresponding input filenames)
- authentication challenges (defined by a true ID with corresponding files, 
  plus the claimed IDS to be tested against)

A write_xml() function will also be provided to convert the tests structure into
one that is compatible with Surrey's existing system.

-------------------------
input_dir: ./videos/
model_dir: ./models/
output_dir: ./output/
file_ext: avi

enrol:
{
  ID: { name: person0 videos: { face0_1 face0_2 face0_3 } }
  ID: { name: person1 videos: { face1_1 face1_2 face1_3 } }
  ID: { name: person2 videos: { face2_1 face2_2 face2_3 } }
}

tests:
{
  test: { ID: { name: person0 videos: { face0_4 face0_5 } } challenge: { person0 person1 } }
  test: { ID: { name: person1 videos: { face1_4 face1_5 } } challenge: { ALL } }
}
--------------------------


1) Face detection
=================
Input: 
- one mobio_inputfile (e.g. examples/inputfile.txt)

Output:
- one mobio_video_faceboxes object (stored in output_dir/<videoname>_faceboxes.txt)
  per video processed. This file contains a list of frames, where each frame contains
  a list of faceboxes. Each facebox specifies a centre (x & y), size (x & y) and 
  score (indicating the strength of the detector output)

See example: mobio_fd_uman_stl_v1

-------------------------
filename: face0_1.avi
frame_length: 40
start_frame: 0
frames: {
  frame:  { facebox: { cx: 11 cy: 12 wx: 20 wy: 30 score: 0.95 } }
  frame:  { facebox: { cx: 21 cy: 22 wx: 20 wy: 30 score: 0.97 }
            facebox: { cx: 51 cy: 52 wx: 20 wy: 30 score: 0.92 } }
  frame:  { }
}
-------------------------


2) Feature localization
=======================
Input: 
- one mobio_inputfile (e.g. examples/inputfile.txt)
- one mobio_video_faceboxes file per video

Output:
- one mobio_video_face_points object (stored in output_dir/<videoname>_facepts.txt)
  per video processed. Again, this contains a list of frames where each frame
  contains a list of faces (each corresponding to a facebox in 
  <videoname>_faceboxes.txt). Each face contains score (based on the feature
  locations, as opposed to the detection score) and a list of feature locations
  (x-position, y-position and feature score)

Functions will be provided to extract particular features from the list (e.g. left and
right eye centres).

See example: mobio_fl_uman_stl_v1

-------------------------
filename: face0_1.avi
frame_length: 40
start_frame: 0
frames: {
  frame:
  {
    face:
    {
      score: 0.89
      points:
      {
        pt: { x: 0 y: 1 score: 2 }
        pt: { x: 1 y: 2 score: 3 }
        pt: { x: 2 y: 3 score: 4 }
      }
    }
  }
  frame: 
  { 
    face: { ... } 
    face: { ... } 
  }
  frame:  { }
}
-------------------------


3) Face authentication
======================
Input: 
- one mobio_inputfile (e.g. examples/inputfile.txt)
- one mobio_video_face_points file per video

Output:
- one mobio_output object (stored in output_dir/<videoname>_results.txt)
  per video processed that stores the video name, the true identity corresponding
  to the video and a score structure for each claimed ID

Videos are divided into segments for video/audio processing. Each segment is assigned
a score. These scores are then combined for the total score of the claimed ID against 
the video.

Functions for read_xml() and write_xml() will also be added for compatability with
Surrey's existing set-up.

See example: mobio_fa_uman_stl_v1

-------------------------
filename: face0_5
actual_id: person0
results: 
{
  result:
  {
    claimed_id: person0
    total_score: 0.87
    segment_length: 40
    start_time: 0
    segments: 
    {
      segment: { score: 0.42 }
      segment: { score: 0.42 }
      segment: { score: 0.42 }
      segment: { score: 0.42 }
      segment: { score: 0.42 }
    }
  }
  result:
  {
    claimed_id: person1
    ...
  }
}

-------------------------

