Generation and detection of alignments in Gabor patterns.
===========================

Version 1.0 - April 18, 2016
by Samy Blusseau <sblusseau@gmail.com>


Introduction
------------

aligned_gabors.m contains an implementation of the generation and
detection algoritms described in the paper:

Generation and detection of alignments in Gabor patterns.


Files
-----

README.txt          - This file.
COPYING             - GNU AFFERO GENERAL PUBLIC LICENSE Version 3.
Makefile            - Compilation instructions for 'make'.
aligned_gabors.m    - Matlab source code for the algorithms presented in the corresponding paper
test.m              - Matlab code to test aligned_gabors.m.



Compiling
---------

Compiling is only necessary for the online demo to run the generation
and detection algorithms. To run the code on your machine, the Matlab
software is sufficient and you don't need to compile the code.

The compiling instruction is just

  make




Running the code
-------------------

An easy way to test the code is to run the script test.m with the command

   test

in a matlab terminal, from the directory containing both test.m and
aligned_gabors.m.

You can edit the test.m file to change the input parameters such as
the total number of elements in the generated stimulus, the number of
aligned elements and the level of angular jitter. It is possible to
choose the size of the stimulus image, although in the related paper
it is not considered as an input parameter but supposed to be fixed to
500 pixels.

Running test.m calls aligned_gabors.m with all necessary arguments:

	- The name of the stimlus png image (currently 'stimulus.png', but
          can be changed to any name with final extension '.png')

	- The name of the target alignment png image (currently
          'target.png', but can be changed to any name with final
          extension '.png')

	- The name of the detection png image (currently
          'output_algo.png', but can be changed to any name with final
          extension '.png')

	- The names of the text files containing respectively the
          coordinates and the orientations of the stimulus elements
          (currently 'pts.txt' and 'ors.txt' respectively)

	- The name of the text file containing the indexes of the
          target elements (currently 'target_idx.txt')

	- The names of the text files containing respectively the
          target's NFA and the detected alignment's NFA (currently
          'nfa_target.txt' and 'nfa_detec.txt').

	- The name of the text file containing the report on the whole
          process (generation and detection; currently, this filename
          is report.txt).

The 9 files the names of which are set by the arguments above are the
output of running test.m. Moreover, the script test.m displays the
three png images.

To run independently the generation and detection steps, you need to
call the functions "generation" and "detection" respectively,
implemented in the file aligned_gabors.m.



Copyright and License
---------------------

Copyright (c) 2016 Samy Blusseau <sblusseau@gmail.com>, Rafael Grompone von Gioi

This is a free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.

This software is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.


Thanks
------

We would be grateful to receive any comment, especially about errors,
bugs, or strange results.