############################ -CSVM- ###################################
This program is an experimental platform exploring new variations on the techniques based on the paper
"Recognizing Handwritten Characters with Local Descriptor and Bags of Visual Words" by Surinta e.a.
Also see te dataset README in the ./datasets/ folder for download instructions for the required
datasets.
####################### -GNU/Linux Usage- #############################
Usage: (gnu/linux using g++, CMake, Make, SWIG, python)
1. Download the repository, if not already done so.
2. Download the dataset as described in the README in the "datasets/" folder.
3. Go to the repository in terminal and type the following:
cmake . (Generates MAKEFILE)
make (builds the project)
cd build/ (change directory to the build folder)
./CSVM [settingsfile] (Execute the program)
or use run (bash script in the root directory, see below for usage or use run -h)
PSO (Quick Guide)
1. Go to /swig/ and execute ./swig.sh for python wrapper generation. This automatically puts the required wrapper in the /PSO/testers/ directory.
2. Go to /PSO/testers, and execute ./start.sh. See /PSO/testers/bandit.py for the settings of the PSO run.
#### Settings file ####
For editting PSO-settings, the file /PSO/testers/bandit.py must be editted.
Example:
Dataset
method MNIST ## MNIST or CIFAR10
nTrainImages 600 ## Nr of images used for training
nTestImages 100 ## Nr of images used for testing
imageWidth 32 ## Integer width used for rescaling the data. If imageWidth <= 0, data will keep the original dimensions
imageHeight 32 ## Integer height used for rescaling the data. If imageHeight <= 0, data will keep the original dimensions
General
Classifier CSVM ## CSVM / LINNET / SVM (csvm, linear network, svm respectively)
Codebook CODEBOOK ## CODEBOOK / DEEPCODEBOOK
nClasses 10 ## Nr of classes in dataset
debugOut FALSE ## use debug output (TRUE/FALSE)
normalOut TRUE ## use normal output (TRUE/FALSE)
Codebook
method KMEANS ## The only supported clustering method at the moment
nClusters 200 ## Nr of centroids used in codebook generation
SimilarityFunction SOFT_ASSIGNMENT ## Activation function of a feature and a centroid. Supported options are: SOFT_ASSIGNMENT, RBF
similaritySigma 0.0001 ## Sigma value for the activation function. There should always be a value here, but it is only used when RBF is used.
FeatureExtractor
method HOG ## Options: HOG (histogram of oriented gradients), LBP (local binary patterns) (deprecated), CLEAN (raw pixels, with standardisation over colour channels). PIXHOG (combination of CLEAN and HOG, adjusting for vector length, and additional ratio parameter for weighting importance of either)
cellSize 6 ## HOG cellsize
cellStride 6 ## HOG cellstride
padding Identity ## Padding options. Currently, Identity should be used.
useColourPixel true ## Toggle whether HOG should append RGBHOGs or just one grey HOG. MNIST Should use 'false', CIFAR could use 'true'
weightRatio 0.5 ## Only relevant for PIXHOG, to weight either CLEAN or HOG more.
ImageScanner ## Settings for extracting patches from an image
patchHeight 12 ## Patch Height
patchWidth 12 ## Patch Width
scanStride 2 ## Patch Stride
nRandomPatches 100000 ## Nr of random patches used for codebook generation.
SVM
Kernel LINEAR ## Type of SVM Kernel. Supported options: LINEAR, RBF
AlphaDataInit 0.0001 ## Initial value for alpha wrt. the data examples
nIterations 2000 ## Number of SVM training iterations
learningRate 0.0001 ## SVM- learningRate
SVM_C_Data 10000000 ## SVM_C for alpha_data
Cost 1 ## Cost
D2 1 ## D2
sigmaClassicSimilarity 100 ## Sigma value for RBF kernel
LinNet ## Linear Network settings
nIterations 10 ## N trainings iterations
initWeight 0.01 ## Initial Weight
learningRate 0.000005 ## Lsearning Rate
ConvSVM ## Marco's CSVM
learningRate 0.000001 ## LearningRate
nIterations 200 ## N trainings iterations
initWeight 0.0000002 ## Initial Weight value
CSVM_C 1000 ## C
L2 TRUE ## Use L2 version instead of L1
#### Parameter optimalisation: ####
## Program description ##
In the PSO folder a parameter optimalisation program can be found.
This program tries to find optimal parameters for a "tester"-program, which are found in the
./PSO/testers/ folder. The tester-file designed for the CSVM program is called bandit.py.
This tester requires the CSVM program in a Python library form. For this SWIG is used, which is
described in the next section.
## Program usage description ##
# Codebook Generation # (Is not used at the moment)
The CSVM wrapper uses a pre-generated codebook for the program. This way a lot of
codebook regeneration time can be spared during optimisation. Codebook-construction settings are described
in ./build/settings.
Set the required settings (ImageScanner, FeatureExtractor, Dataset, Codebook) to the experiment-settings.
Next, the codebook should be generated. This can be done by executing /PSO/testers/generateCodebook.sh.
This script uses the settingsfile from "/build/settings"
If all went well, the file codebook.bin will be added to ./PSO/testers.
# Execution #
The program can be executed by calling the start.sh script in ./PSO/testers/.
#### SWIG-wrapping: ####
For SWIG-wrapping you should first install SWIG (http://www.swig.org/) if not already installed.
The CSVM program is wrapped for Python using SWIG. To adapt the python interface of CSVM,
go to the "swig" folder. The experiment.[cc/h] files describe functions that will be wrapped to python.
The wrapping and compilation process is described, and executable in the swig.sh script.
This script automatically copies the produced python library to the "./PSO/testers/" location,
where the library is needed for parameter optimalisation.
########################## -run script Usage- ############################
Utility to run experiments.
Usage:
run [options]
-h Display usage
-r <X> Repeat experiment X times
-R <X> Repeat experiment X times, using <f>_X as settingsfile
-f <f> Use <f> as settingsfile (default: 'settings')
-s Silent running,exept for the final 'score' output
-l Surpress log generation
-g Surpress graphic output
-d <f> Document results and logs in the new folder <f>, subdirectory of build/logs
-a Play alert sound when done
-m Add a memo to logfile
The output above is the result of using run -h or run --help. This will be a more in-depth description.
To use run in the most straightforward manner one could simply use the command without any flags. The system will then run using the settingsfile in the build directory. A detailed logfile including settings and output will be stored in build/logs. The file will be titled LOG_[date]_[time]. Logfile generation can be omitted using -l, but this is not recommended. A more detailed log will exist in build/logs/LAST_RUN. In this map all temporary files asociated with this last run will be stored. These files include all generated graphs, logfiles and errorlogs as well as a copy of the used codebook. All these files will be overwritten during the next run. If a detailed logging of the experiment is desired one can use the -d <file> flag, in which <file> represents the name of the new map to be created in build/logs to which all items in build/logs/LAST_RUN will be copied, essentially documenting the entire run.
Using the -r <x> flag the experiment will be repeated <x> times. If the document (-d) option is active, several maps will be generated, each having a numbered suffix added to the directoryname. This numbering can also be aplied to several settingfiles to ensure, using the option -R, that each of those runs uses a different settingsfile. This is also compatible with the -f <filename> flag, which alters the name of the settingsfile to <filename>.
To add further precision to the logging process, a memo may be added tot the logfile, using the -m flag. This will open a terminal text editor prior to initialization, enabling the user to add a few lines of comment to the logfile before the program executes.
The graphic output (which can be surpressed with the -g flag) renders an image (png) of nine graphs, each of which is also stored seperately in build/logs/LAST_RUN or in the optional document folder. each grpah consists of an upper and a lower graph, alligned to the same x-axis, which depicts the individual training rounds. Each training round represents the classifier going through all the trainingsdata (nTrainImages) once. The axis therefore goes from zero to [nIterations].
The upper part of the graph shows the values for the Primary Objective Function as well as the performance (in percentage) over time. Note that there are two different y-axes: the left depicts the value for the Objective Function, the right for the classification Performance, for this one classifier.
The lower part of the graph shows the mean output values for this classifier, one line for positive values, one for negative. The coloured range around those lines depict the standard deviation of those values, positive deviation calculated seperately from negative deviation, per line.
The scale of each graph is matched to all others, so direct comparisons can be made.
All of the data used for generating these graphs (which is done in R[1]) can be found in the csv files stored in build/logs/LAST_RUN.
############################## -Windows Usage- ############################
Usage: (Windows using Microsoft Visual Studio)
1. Download the repository, if not already done so.
2. Open CSVM.sln
3. To execute: Go to the build folder in terminal, and execute from there
(note: If you execute the program from visual studio, the link to images is relative to
the main (CSVM) folder. This causes to program to crash in a controlled way, since it cannot find the
.png files. Because of this you have to execute the program by hand from the "build" folder. Either by a double-click
or in terminal. Using the terminal is adviced, since the program will disappear directly when finished otherwise.)
Further usage regarding SWIG and Parameter-Optimalisation on Windows systems have not yet been tried out.
[1] R Development Core Team (2008). R: A language and environment for statistical computing. R Foundation for Statistical Computing, Vienna, Austria. ISBN 3-900051-07-0, URL http://www.R-project.org.