README.txt

#########################################################
###################### Setting up #######################
#########################################################

1) Install all the dependencies in requirements.txt

#########################################################
############ Ensemble Detector Instructions #############
#########################################################
This section gives the main instruction to execute our final ensemble model.

1) Our main ensemble detector is located in the /ensemble_detector folder
2) The trained Viola-Jones models are located in the /ensemble_detector/classifier folder
3) The templates used for template matching are located in the /ensemble_detector/template folder
4) There are 3 main scripts: ensemble_detector.py, ensemble_detector_visualizer, input_generator.py

To generate baselines by our model:

1) cd to the /emsemble_detector folder

2) Run 'python input_generator' to generate a text file containing the paths to the test images.
   ** This will generate a file named 'input.txt'. An example is given in the folder.
   ** Format for each line in 'input.txt': <path_to_image> <image_index>
   ** IMPORTANT: To use this script please ensure that the /datasets are structured according to the original structure.
   ** Alternatively, you can generate the 'input.txt' on your own.

3) Run 'python input_generator -ii input.txt' to execute detections and generate baselines by our ensemble model.
   ** The ensemble detector will execute the two-stage detection.
   ** The baselines will be generated in the /ensemble_detector/baseline folder. (NOT THE GIVEN BASELINE FOLDER)
   ** IMPORTANT: To evaluate the baselines, copy them to the desired location.
   ** IMPORTANT: Please DELETE the baseline folder before each new execution of detector. Otherwise, the new detections will be appended to the old files.
   
To visualize detections by our model:

1) cd to the /emsemble_detector folder

2) Run 'python ensemble_detector_visualizer.py -ip <input_image_path>'
   ** A window with our detections will be shown. 
   ** Press Esc to close the window.
   ** If the rectangles/fonts are too big/small, feel free to adjust them in the 'visualize_detections' method


#########################################################
##################### Peripherals #######################
#########################################################
This section is OPTIONAL and mainly shows our effort in building our final model. 
WARNING: As these are not part of the final model, they are not actively maintained and might have execution errors.

They include:
1) Other methods we have attempted
2) Image augmentation to generate more training samples
3) Training scripts for Viola-Jones

################ Other Methods Attempted ################
A) Standalone Cascade Classifier
NOTE: To run training for openCV cascade classifier, please make sure openCV dependencies are available.

1) The related content can be found in the /cascade_classifier folder
2) For detection, 
	2.1) Run 'python detector.py <classifier> <image> <3_digit_image_idx> <output_path>'
3) For training,
	3.1) Run 'python generate_bg.py <folder_with_neg_egs>' // create file containing negative sample paths
	3.2) Run 
		 'python generate_info.py <folder_with_pos_egs>'  // for additional training images
		 'pthon generate_info_xml.py'  // for xml annonations provided by course
		 'opencv_createsamples -info info.dat -num <#_pos_egs> -w 50 -h 50 -vec waldo.vec' // to create positive samples data
	3.3) Run 'opencv_traincascade -data classifier -vec waldo.vec -bg bg.txt -numPos <#_pos_egs> -numNeg <#_neg_egs> -numStages <#_stages> -w <window_width> -h <window_height>' // execute training process

B) HOG SVM Detector

1) The related content can be found in the /hog_svm folder
2) For detection,
	2.1) For sklearn version, run 'python test_HOG_SVM.py'
	2.2) For openCV version, run 'python OpenCV_test_HOG_SVM.py'
3) For training,
	3.1) For sklearn version, run 'python train_HOG_SVM.py'
	3.2) For openCV version, run 'python OpenCV_train_HOG_SVM.py'

C) Basic Template Matching

1) The related content can be found in the /template_matching folder
2) For detection, run 'python basic_template_matching.py -t <template_folder_path> -i <image_idx>'

################## Image Augmentation ###################
NOTE: The positive and negative samples generated by us can be found in /datasets/PositiveSamples and /datasets/NegativeSamples respectively
The related content can be found in the /img_aug.
There are three scripts to create and augment positive samples for data 
preparation. 

1) Generate original positive samples
	1.1) Run 'gen_train_pos_img.py' to crop true positives from the annotation folder /datasets/Annotations. 

      	     ** Create the directory 'datasets/PositiveSamples' which contain the directories 'waldo', 'wenda' and 'wizard' for the script to save 
the cropped positive samples to.
    	1.2) Process the original images manually and save into the directories 'datasets/PositiveSamples/waldo/head/original' 
and 'datasets/PositiveSamples/waldo/torso/original'. 
    	1.3) The following directories should then be created in the 'head' and 'torso' 
directories, 'brightness', 'contrast', 'gaussblur', 'gaussnoise' as such, and the same steps repeated for 'wenda' and 'wizard':
	
	datasets

	|-PositiveSamples
  
		|-waldo
    
			|-torso
      
				|-brightness
      
				|-contrast
      
				|-gaussblur
      
				|-gaussnoise
      
				|-original
    
			|-head
      
				|-brightness
      
				|-contrast
      
				|-gaussblur
      
				|-gaussnoise
      
				|-original
  
		|-wenda
  
		|-wizard

2) Generate augmented images
	2.1) Run 'augment_positive_samples.py'
	     ** Augmented images will be saved to their respective directories
	     ** Change parameters in 'augment_positive_samples.py' to change augmentation level
	     ** Default parameters are:
		sigmas = [0.5, 0.75, 1, 1.25, 1.5], 
brightness_levels = [-20, -15, -10, -5, 5, 10 ,15, 20], 
contrast_levels = [0.85, 0.9, 0.95, 1.05, 1.1, 1.15]
	     ** There are boolean values that allow the script to skip certain augmentations by setting them to False. 
By default, horizontal flip and rotation are set to False.

3) Count number of images for each character and body parts
	3.1) Run 'count_pos_samples.py'
	

########### Training Scripts for Viola Jones ############
The related content can be found in the /training folder
NOTE: To run training for openCV cascade classifier, please make sure openCV dependencies are available.

1) Data generation
	1.1) Run 'python data_generator.py'
	     ** /training/data folder will be created, which contains all training data needed
2) Training
	2.1) Run 'python trainer.py -w <width> -bt <booster> -minHitRate <minHitRate> -maxFalseAlarmRate <maxFalseAlarmRate> -mode <mode>"
	    ** Automatically train for all characters and all body parts
	    ** /training/trained_models folder will be created, will contians all trained models
3) Validation
	3.1) Run 'python validator.py'
	    ** /training/baseline folder will be created, which contains all the baselines for all models in /training/trained_models
	    ** 'eval.txt' will be generated, which contains the average mAP for all the models (aggregated according to training parameters)