Graphical Interface

This section presents the descriptions of modules, classes and methods that handle and run the GUI.

trackUI module

This module runs the graphical interface. It contains the classes:

class trackUI.Dialog_results[source]

Class definition for PF tracking results dialog.

class trackUI.Dialog_facedetector[source]

Class definition for face detectors dialog.

class trackUI.Dialog_plotError[source]

Class definition for tracking error dialog.

class trackUI.MainWindow[source]

Main class containing the main window of the graphical interface.

This class cointains all the methods needed for running the graphical interface since the main window. Here particle filter parameters and models definitions are offered for testing face tracking in video sequences.

Supported options:

  • filter algorithms (SIS, SIS, GPF, APF),

  • number of particles,

  • resampling algorithms (multinomial, systemactic, stratified, residual),

  • resampling percent,

  • estimation algorithms (weighted mean, maximum weight, robust mean),

  • robust mean percent,

  • state space defintions,

  • observation models (HSV color-based, LBP-based)

  • input video (from webcam or disk)

  • save estimation

OpenFileSignal()[source]

Open a window for selecting an input video file.

RobustOutput()[source]

Method to enable or disable Robust Mean percent options.

closeEvent(event)[source]

Show message for being sure to close the graphical interface.

enableResample_fromAlgorithm()[source]

Method to enable or disable resampling options in relation to the PF algorithm.

facedetector()[source]

Get face detector algortihm and close face detector dialog.

getErrorPath()[source]

Select a path to save error.

Open a window for selecting the name of the file (.txt file wich will contain the algortihm erro per each frame and iteration) and where to store it on disk.

getEstPath()[source]

Select a path to save estimates.

Open a window for selecting the name of the file (.txt file wich will contain the particle estimation track per each frame of every iteration) and where to store it on disk.

get_algorithm()[source]

Get particle filter algorithm.

get_estimate()[source]

Get estimation’s algorithm for output.

get_n_particles()[source]

Get number of particles.

get_obsModel()[source]

Get particle filter algorithm.

get_resample()[source]

Get resample algorithm if the particle filter algorithm is not SIS.

get_resamplePercent()[source]

Get resample percent if the particle filter algorithm is G_PF

get_robustPercent()[source]

Get robust percent of particles for robust mean estimation algorithm.

get_stateSpace()[source]

Get particle filter algorithm.

openFaceDialog()[source]

Open face detector dialog.

openGtFile()[source]

Open window for selecting ground truth file on disk.

openResultsDialog()[source]

Open results dialog.

run()[source]

Get the all selected filter and model parameters and then call the face detector dialog.

run2DFfilter()[source]

Run face tracking based on particle filter.

saveOutVideo()[source]

Save the resulting video.

Open a window for selecting the name of the video resulting from the tracking based on PF algorithm and where to store it on disk.

showError()[source]

Plot precision and recall error metrics per frame.

track module

This module does the same as the graphical interface but as a Python package.

class pftracker.track.Track(video=None, algorithm='G_PF', n_particles=100, detector='CaffeModel', estimate='weighted_mean', resample='systematic', resamplePercent=50, robustPercent=20, obsmodel='HSV color-based', stateSpace='dynamic_bbox')[source]

Track class provides top-level of pftracker module for user handeling. Here are defined all the particle filter parameters and target model specifications for perfoming the task of face traking in video sequences.

run(iterations, gt, errorFile, saveTrackFile, saveVideo)[source]

Perform the face tracking based on particle filter.

plotError()[source]

Plot precision and recall error metrics.

Parameters

  • video (str, optional) – Path to the input video file (.mp4 or .avi format). Default is the reference to the webcam (None)

  • algorithm (str, optional) – Particle filter algorithm. Default is ‘G_PF’

  • n_particles (int, optional) – Number of particles. Default is 100

  • detector (str, optional) – Face detector algorithm. Default is ‘CaffeModel’

  • estimate (str, optional) – Estimate method. Default is ‘weighted_mean’

  • resample (str, optional) – Resampling method. Default is ‘systematic’

  • resamplePercent (int, optional) – Resampling percent. Default is 50

  • robustPercent (int, optional) – Resampling percent. Default is 20

  • obsmodel (str, optional) – Observation model. Default is ‘HSV color-based’

  • stateSpace (str, optional) – State space model. Default is ‘dynamic_bbox’

Supported PF algorithms:

  • ‘SIS’: Sequential Importance Sampling filter

  • ‘SIR’: Sequential Importance Resampling filter

  • ‘G_PF’: Generic particle filter

  • ‘APF’: Auxilliary particle filter

Supported Face detectors:

  • ‘HaarCascade’: Viola and Jones (V&J) detector

  • ‘CaffeModel’: Single Shot Detector (SSD)

  • ‘dlib’: Histogram of Oriented Gradient (HOG)

Supported estimate methods:

  • ‘weighted_mean’: Weighted mean method

  • ‘MAP’: Maximum weight method

  • ‘robust_mean’: Robust mean method

Supported resampling methods:

  • ‘systematic’: Systematic resampling

  • ‘stratified’: Stratified resampling

  • ‘residual’: Residual resampling

  • ‘multinomial’: Multinomial resampling

Supported observation models:

  • ‘HSV color-based’: Color model for weighing the particles

  • ‘LBP-based’: Texture model for weighing the particles

Supported state space models:

  • ‘dynamic_bbox’: Self updating bounding box model

  • ‘5_variables’: Five variables state space model

  • ‘6_variables’: Six variables state space model

Raises

AssertionError – Exception raised if the path to the input video file does not contain .mp4 or .avi extension.

Example

First construct the object and defined input video, filter parameters and target model if you want different options than the default ones.

from pftracker.track import Track
pf = Track(video="pftracker\input\Aaron_Guiel\Aaron_Guiel5.avi")

Then run the algorithm with the previous definitions and specify the number of algorihm iterations and ground truth file is you want to calculate precision and recall error metrics. Also specify errorFile, saveTrackFile and saveVideo for saving error, estimates and resulting video files.

pf.run(iterations=2,
       gt="pftracker\input\Aaron_Guiel\Aaron_Guiel5.labeled_faces.txt")

Note that if you want to specify a file for saving error you should provide the ground truth file too.

After that you are going to see the face tracking performing over the selected input video.

If you want to plot the precision and recall metrics per frame (and per iteration in case of you have more than one) and you provided the ground truth file previously, then you can run:

pf.plotError()
plotError()[source]

Plot precision and recall error metrics.

This method plots precision and recall per frame if a ground truth file was provided. If the number of algorithm runs if bigger than one, then precision and recall are plotted per particle filter algorithm run too.

run(iterations=10, gt=None, errorFile=None, saveTrackFile=None, saveVideo=None)[source]

Perform the face tracking based on particle filter.

Parameters

  • iterations (int, optional) – Number of algorithm iterations. Default is 10. If the input video is the reference to the webcam then the video is recorded just once and therefore the algorithm iterations are always equal to 1.

  • gt (str, optional) – Path to the ground truth file. Without this file is not posible to calculate precision and recall error metrics. Default is None

  • errorFile (str, optional) –

    Path to a .txt file for saving precision, recall and F1-score error metrics. Default is None (do not save error).

    Example

    pf.run(errorFile="pftracker\output\pf_error.txt")

    In case of the number of iterations is greater than 1, the errors of each tracking iteration are saved in the same .txt file separated by a blank line. Besides, average precision, recall, elapsed time and fps per iteration are going to be saved at the end of the file. Note that if you want to save the error file you should provide the ground truth file too.

  • saveTrackFile (str, optional) –

    Path to the estimate .txt file. Default is None (do not save estimates).

    Example

    pf.run(saveTrackFile="pftracker\output\pf_estimates.txt")

    In case of the number of iterations is greater than 1, all the estimates of each tracking iteration are saved in the same .txt file separated by a blank line.

  • saveVideo (str, optional) –

    Path to the output video file. Default is None (do not save video). Always the output file is a .avi format, so please specify this format when write the path.

    Example

    pf.run(saveVideo="pftracker\output\pf_output.avi")

    In case of the number of iterations is greater than 1 and you want to save all the resulting videos from tracking, you just have to specify one name for a video file as explain before and the number of the iteration is going to be added automatically to that name.

    Example

    If you run the command:

    pf.run(2, saveVideo="pftracker\output\pf_output.avi")

    The resulting video file names are:

    pf_output0001.avi

    pf_output0002.avi

Raises

  • AssertionError – Exception raised if the path to the ground truth file does not contain the .txt extension.

  • AssertionError – Exception raised if the path to the error file does not contain the .txt extension.

  • AssertionError – Exception raised if the path to the estimates file does not contain the .txt extension.

  • AssertionError – Exception raised if the path to the output video file does not contain .avi extension.

Interfacing UI

class pftracker.modules.interfacingUI.ParticleTracker(video, algorithm, n_particles, detector, estimate, resample, resamplePercent, robustPercent, obsmodel, stateSpace)[source]

Class interfaces particle filter to handle face tracking problem.

This class interfaces particle filter algorithms to work in the face tracking in video sequences task. Video sequences can be recorded from computer’s webcam or .mp4 or .avi files loaded from disk.

Parameters

  • video (str, optional) – Path to the input video file (.mp4 or .avi format). Default is the reference to the webcam

  • algorithm (str) – Particle filter algorithm

  • n_particles (int) – Number of particles

  • detector (str) – Face detector algorithm

  • estimate (str) – Estimate method

  • resample (str) – Resampling method

  • resamplePercent (int) – Resampling percent

  • robustPercent (int) – Resampling percent

  • obsmodel (str) – Observation model

  • stateSpace (str) – State space model

Supported PF algorithms:

  • ‘SIS’: Sequential Importance Sampling filter

  • ‘SIR’: Sequential Importance Resampling filter

  • ‘G_PF’: Generic particle filter

  • ‘APF’: Auxilliary particle filter

Supported Face detectors:

  • ‘HaarCascade’: Viola and Jones (V&J) detector

  • ‘CaffeModel’: Single Shot Detector (SSD)

  • ‘dlib’: Histogram of Oriented Gradient (HOG)

Supported estimate methods:

  • ‘weighted_mean’: Weighted mean method

  • ‘MAP’: Maximum weight method

  • ‘robust_mean’: Robust mean method

Supported resampling methods:

  • ‘systematic’: Systematic resampling

  • ‘stratified’: Stratified resampling

  • ‘residual’: Residual resampling

  • ‘multinomial’: Multinomial resampling

Supported observation models:

  • ‘HSV color-based’: Color model for weighing the particles

  • ‘LBP-based’: Texture model for weighing the particles

Supported state space models:

  • ‘dynamic_bbox’: Self updating bounding box model

  • ‘5_variables’: Five variables state space model

  • ‘6_variables’: Six variables state space model

eval_pf(gt)[source]

Evaluate particle filter algorithm results.

This function calculate precision and recall metrics for the resulting tracking.

Parameters

gt (str) – path to ground truth .txt file

Returns

8-element tuple containing

  • P (array): precision value per frame, array with (1, number_of_frames) dimension

  • R (array): recall value per frame, array with (1, number_of_frames) dimension

  • P_mean (float): precision mean value

  • R_mean (float): recall mean value

  • P_std (float): precision standard deviation value

  • R_std (float): recall standard deviation value

  • F1Score (float): F-1-score metric

face_tracking(saveVideo)[source]

Run the especified particle filter algorithm for face tracking.

Parameters

saveVideo (str) – Path to the output video file. None means do not save video

Returns

2-element tuple containing

  • t_elapsed (float): Approximate execution time of the algorithm in the face tracking task.

  • fps (float): Approximate number of fps.

Raises

  • AssertionError – Exception raised if the reference to the webcam failed.

  • AssertionError – Exception raised if the reference to the input video failed.

save_estimation(file_name)[source]

Save the particle estimation for each frame into a .txt file

Parameters

file_name (str) – path to output .txt file

Running filter

class pftracker.modules.runFilter.RunFilter(model, algorithm, N, estimate, resample, resamplePercent, robustPercent=None)[source]

Run an especific particle filter algorithm for the estimation problem in video sequences.

This is a general class that can be run for solving any PF estimation problem as well as the ParticleFilter class. Its whole structure is based on ParticleFilter class callings.

Parameters

  • model – Object of class describing the especific model where apply the particle filter estimation

  • algorithm (str) – PF algorithm

  • n_particles (int) – Number of particles

  • estimateOutput (str) – Output estimate method

  • resample (str) – Resampling method

  • resamplePercent (int) – Resampling percent

  • robustPercent (int) – Resampling percent

  • output (str, optional) – Path to optional output txt file

eval_alg(gt_file)[source]

Returns the evaluation (error) of particle filter algorithm results.

Parameters

gt_file (str) – path to ground truth .txt file

get_pf_estimation()[source]

Get particle filter estimation.

save_estimate(file_name)[source]

Save the particle estimation for each frame into a .txt file.

Parameters

file_name (str) – path to output .txt file

tracking()[source]

Do the particle filter tracking.

Returns

2-element tuple containing

  • (float): Approximate execution time of the algorithm in the face tracking task.

  • (float): Approximate number of fps.