Gestaltic Grouping of Line Segments
===================================

Version 2.1 - December 6, 2017
by Boshra Rajaei <b.rajaei@sadjad.ac.ir>
and Rafael Grompone von Gioi <grompone@gmail.com>


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

The algorithm is an implementation of a paper submitted to ipol with similar
title.  All the codes has been implemented in Matlab R2014a.


Requirements
------------

Matlab, a Matlab supported C compiler, and Ghostscript's gs.


Compiling
---------

Ghostscript's gs program is assumed to be instaled at '/usr/bin/gs'; if this
is not the case, please put the right path on line 23 of 'GG.m'.

Compile by executing the following two commands:

  mex MEX_lsd_cmd.c lsd.c
  mcc -a ./ -m GG

If 'mex' and 'mcc' are not on your current path, you may need to include
the full path to the location of the instalation of Matlab.


Running
-------

The start point function is GG.m with the following prototype

  GG(image, image_type, rho, theta, k)

input:
  image            input image
  image_type       input image format (e.g. png jpg etc)
  rho              maximum distance between line segment tips for
                   a good continuation (in pixels)
  theta            maximum angle between line segments for a good continuation
                   (in degree)
  k                maximum number of segments in a grouping

output:
  <name>_GC        good continuations image with similar format as input
  <name>_LSD       line segments image with similar format as input
  <name>_Bars      parallel segmets image with similar format as input
  <name>_NLA       non-local alignments image with similar format as input
  <name>_Residual  residual image with similar format as input (the LSD
                   segments that are not grouped by any of grouping rules)
  n_det.txt        the number of initial line segments, good continuations,
                   bars, non-local alignments, residual ungrouped segments,
                   respectively, which are printed out in n_det.txt file.

The function may be execute using the 'run_GG.sh' script generated by mcc.
The syntax is:

  run_GG.sh <MATLAB_PATH> <image name> <image type> <rho> <theta> <k>

The following example apply the method on the image 'test.png':

  ./run_GG.sh /usr/local/matlab/matlab test png 10 100 10

This example worked correctly on a Linux system in which Matlab was installed
on path '/usr/local/matlab/matlab'. Another common installation path is
'/usr/local/matlab'. Please check the correct path in your system and adapt the
execution line.

This example should produce the following files:

  test_GC.png
  test_LSD.png
  test_Bars.png
  test_NLA.png
  test_Residual.png
  n_det.txt

Please note that the Matlab path may change from system to system, the previous
example worked on one system running Lynux and Matlab R2015b. You may need to
remplace the second argument to the correct path on your system.


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

See the header of each file. Most of the code are distributed under the terms
of the GNU Affero General Public License, included in the file 'COPYING'. The
following authors and copyrights are included in different files:

Copyright (c) 2016-2017 boshra rajaei <b.rajaei@sadjad.ac.ir>

Copyright (c) 2007-2011 rafael grompone von gioi <grompone@gmail.com>

Copyright (c) 2014 Paul-Darius Sarmadi <paul-darius.sarmadi@telecom-sudparis.eu>

Copyright 2010-2011 by Timothy E. Holy

(c) Primoz Cermelj, primoz.cermelj@email.si


Thanks
------

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