readme update and train / test small updates

README.md

@@ -1,3 +1,88 @@
 # HOG-Pedestrian-Detector
-MATLAB implementation of a basic HOG + SVM pedestrian detector. 
-Computer Science Master thesis: https://upcommons.upc.edu/bitstream/handle/2099.1/21343/95066.pdf?sequence=1&isAllowed=y
+This repository contains the code for a MATLAB implementation of a basic HOG + SVM pedestrian detector form my Computer Science Master [thesis](https://upcommons.upc.edu/bitstream/handle/2099.1/21343/95066.pdf?sequence=1&isAllowed=y)
+
+## Disclaimer
+
+If you are going to use this code, please read the `LICENCE` and keep in mind that I `PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND`.
+
+I partially adapted this code-base to newer versions of MATLAB but is very likely you find discrepancies in how some MATLAB functions work. 
+I am in general happy to help understanding the project if you ask nicely but since the implementation of the project is now several years old and MATLAB has evolved, some functions might behave differently and I won't be updating the project continuously nor answering about how to update the code to newer MATLAB versions.
+
+## Requirements
+
+* MATLAB >= R2017b
+* [libsvm](https://github.com/cjlin1/libsvm/tree/v322) >= 3.22
+
+## Installation
+
+Please refer to MATLAB and libsvm documentation to install.
+
+
+
+## Data
+
+
+
+## Run
+
+The project was developed on a Windows machine and now being resurrected on a Linux one, so you should be good in any platform as long as you can run MATLAB.
+
+### Setting the environment
+
+1. Add the `libs` directory and **all** sub-directories to MATLABs path.
+Either through the [command window](https://www.mathworks.com/help/matlab/ref/addpath.html) or through the GUI.
+
+2. Make sure `libsvm` is visible to MATLAB. If you are not sure if your installation of `libsvm` went alright, you can check with:
+```matlab
+which -all svmtrain
+```
+Which should show something like:
+```
+~/HOG-Pedestrian-Detector/libs/libsvm-3.22/matlab/svmtrain.mexa64
+/usr/local/MATLAB/R2017b/toolbox/stats/stats/svmtrain.m                 % Shadowed
+```
+
+There are several entry points to the project, but here the two main ones are shown:
+
+### Train
+
+Assuming there's a `models` directory where trained models will be saved and that the positive and negative images can be found in `dataset/Test/pos` and `dataset/Test/neg` respectively.
+Train an SVM model named `test`
+```matlab
+model = train_svm("test", ["./models", "dataset/Test/pos" "dataset/Test/neg"]);
+```
+
+### Eval
+
+To evaluate the just trained model:
+```matlab
+test_svm(model.test, ["dataset/Test/pos" "dataset/Test/neg"]);
+```
+
+Note `test_svm` expects `model.<model-given-name-to-train-function>`...
+
+### PCA versions of train / test
+
+```matlab
+[model, Ureduce] = train_svm_PCA("test_pca", ["./models", "dataset/Test/pos" "dataset/Test/neg"]);
+test_svm_PCA(model.test_pca, Ureduce, ["dataset/Test/pos", "dataset/Test/neg"]);
+```
+
+
+
+## Known issues & contributions
+
+Old MATLAB version used to concatenate strings by enclosing them between squared brackets but doesn't look like valid any longer. In that case you should use the `join` function. For example when constructing paths, so:
+
+```matlab
+path = ['folder', 'filename', '.extension']  % this is wrong!
+path = strcat('folder', 'filename', '.extension')  % this is right!
+```
+
+
+
+If you enjoyed this repository and find things that are not working any longer, you are very welcome to open a PR with fixes and I'll happily introduce them.
+
+
+

cross_validate.m

@@ -40,7 +40,7 @@
                 fprintf('<gamma=%d, cost=%d> \n\n',g,c);
 
                 % writing crossvalidation log file
-                log_file = fopen([model_save_path,'.cv'],'a');
+                log_file = fopen(strcat(model_save_path,'.cv'),'a');
                 fprintf(log_file, sprintf('<gamma=%f, cost=%f>: acc=%f \n\n',g,c,cv));
                 fclose(log_file);
 
@@ -88,7 +88,7 @@
             fprintf('<cost=%d> \n\n',c);
 
             % writing crossvalidation log file
-            log_file = fopen([model_save_path,'.cv'],'a');
+            log_file = fopen(strcat(model_save_path, '.cv'),'a');
             fprintf(log_file, sprintf('<cost=%f>: acc=%f \n\n',c, cv));
             fclose(log_file);
 

dataset/.gitignore

@@ -0,0 +1,4 @@
+# ignore everything
+*
+# but this file
+!.gitignore

models/.gitignore

@@ -0,0 +1,4 @@
+# ignore everything
+*
+# but this file
+!.gitignore

test_svm.m

@@ -96,9 +96,9 @@
                 % saving hard image for further retrain
                 if safe
                     [~, name, ext] = fileparts(positive_images(i).name);
-                    saving_path = [images_path,'/hard_examples/false_neg/',...
+                    saving_path = strcat(images_path,'/hard_examples/false_neg/',...
                                    name,...
-                                   '_n_wind_',num2str(l), ext];
+                                   '_n_wind_',num2str(l), ext);
 
                    % writting image 
                    imwrite(windows(:,:,:,l), saving_path); 
@@ -194,14 +194,14 @@
 
                    if strcmp(neg_method, 'pyramid')
                        [level, num_image] = get_window_indices(wxl, l);
-                       saving_path = [images_path,'/hard_examples/false_pos/',...
+                       saving_path = strcat(images_path,'/hard_examples/false_pos/',...
                                       name,...
                                       '_l',num2str(level),...
-                                      '_w',num2str(num_image),ext];
+                                      '_w',num2str(num_image),ext);
                    else
-                        saving_path = [images_path,'/hard_examples/false_pos/',...
+                        saving_path = strcat(images_path,'/hard_examples/false_pos/',...
                                        name,...
-                                       '_n_wind_',num2str(l), ext];
+                                       '_n_wind_',num2str(l), ext);
                    end
                   % writting image 
                   imwrite(windows(:,:,:,l), saving_path); 

test_svm_PCA.m

@@ -24,8 +24,8 @@
 
     % path stuff
     if nargin < 3
-        positive_images_path = uigetdir('images','Select positive image folder');
-        negative_images_path = uigetdir('images','Select negative image folder');
+        positive_images_path = uigetdir('dataset','Select positive image folder');
+        negative_images_path = uigetdir('dataset','Select negative image folder');
         if safe
           images_path = uigetdir('images','Select base image path');
         end
@@ -99,9 +99,9 @@
                 % saving hard image for further retrain
                 if safe
                     [~, name, ext] = fileparts(positive_images(i).name);
-                    saving_path = [images_path,'/hard_examples/false_neg/',...
+                    saving_path = join(images_path,'/hard_examples/false_neg/',...
                                    name,...
-                                   '_n_wind_',num2str(l), ext];
+                                   '_n_wind_',num2str(l), ext);
 
                    % writting image 
                    imwrite(windows(:,:,:,l), saving_path); 

train_svm.m

@@ -19,8 +19,8 @@
     %% path stuff
     if nargin < 2
         model_save_path = uigetdir('.models','Select model save folder');
-        positive_images_path = uigetdir('.images','Select positive image folder');
-        negative_images_path = uigetdir('.images','Select negative image folder');
+        positive_images_path = uigetdir('dataset','Select positive image folder');
+        negative_images_path = uigetdir('dataset','Select negative image folder');
 
         if isa(model_save_path,'double')  || ...
            isa(positive_images_path,'double')  || ...
@@ -53,12 +53,14 @@
     train_params = get_params('train_svm_params');  
     kernel_type = train_params.kernel;
     cost_range = train_params.cost_range;
-    gamma_range = train_params.gamma_range; 
+    gamma_range = train_params.gamma_range;
+
+    disp(train_params);
 
     svm_params = ...
         cross_validate(kernel_type,cost_range,gamma_range,...
                        train_matrix, labels, ...
-                       [model_save_path,filesep,model_name]);
+                       strcat(model_save_path,filesep,model_name));
 
 
     % just for fixing GUI freezing due to unic thread MatLab issue
@@ -74,8 +76,8 @@
     svm_elapsed = toc(svm_start);
     fprintf('SVM training done in: %f seconds.\n',svm_elapsed);
 
-    fprintf(['Saving model in ',model_save_path, model_name, '.mat','\n']);
-    save([model_save_path,filesep,model_name, '.mat'], '-struct','new_model',model_name);
+    fprintf(strcat('Saving model in ',model_save_path, model_name, '.mat','\n'));
+    save(strcat(model_save_path,filesep,model_name, '.mat'), '-struct','new_model',model_name);
 
 
 end

train_svm_PCA.m

@@ -62,7 +62,7 @@
     svm_params = ...
         cross_validate(kernel_type,cost_range,gamma_range,...
                        train_matrix, labels, ...
-                       [model_save_path,filesep,model_name]);
+                       strcat(model_save_path,filesep,model_name));
 
 
     % just for fixing GUI freezing due to unic thread MatLab issue
@@ -78,11 +78,11 @@
     svm_elapsed = toc(svm_start);
     fprintf('SVM training done in: %f seconds.\n',svm_elapsed);
 
-    fprintf(['Saving model in ',model_save_path, model_name, '.mat','\n']);
-    save([model_save_path,filesep,model_name, '.mat'], '-struct','new_model',model_name);
+    fprintf(strcat('Saving model in ',model_save_path, model_name, '.mat','\n'));
+    save(strcat(model_save_path,filesep,model_name, '.mat'), '-struct','new_model',model_name);
 
-    fprintf(['Saving Reduced Singular Vectors matrix in ',model_save_path, model_name, '_reduced_SVs.mat','\n']);
-    save([model_save_path,filesep,model_name, '_reduced_SVs.mat'], 'Ureduce');
+    fprintf(strcat('Saving Reduced Singular Vectors matrix in ',model_save_path, model_name, '_reduced_SVs.mat','\n'));
+    save(strcat(model_save_path,filesep,model_name, '_reduced_SVs.mat'), 'Ureduce');
 
 
 end