# Morphological snakes #

- Author    : Luis Alvarez <lalvarez@dis.ulpgc.es>
              Luis Baumela <lbaumela@fi.upm.es>
              Pedro Henriquez <phenriquez@ctim.es>
			  Pablo Marquez-Neila <pmarquezneila@gmail.com>
- Copyright : (C) 2009-2011 IPOL Image Processing On Line http://www.ipol.im/
- License   : GPL v3, see license.txt

* Overview *
This source code provides an implementation of the "A Real Time Morphological Snakes Algorithm", 
as described in IPOL
	http://www.ipol.im/pub/algo/abmh_real_time_morphological_snakes_algorithm/

* Compilation instructions *
See more details http://www.ipol.im/pub/algo/abmh_real_time_morphological_snakes_algorithm/Readme.pdf
1- Compiling morphological snakes source code
1.1- Make morphological snakes
1.1.2- Windows
	The project has a GNU makefile. To compile the project, you can open a console (cmd) and go
	to the directory where you have decompressed MorphologicalSnakes zip file. Next you go to
	the source directory. (your_path/MorphologicalSnakes/source). In the file
	WindowCompilationSample.bat located in the MorphologicalSnakes/source path, you can
	find bat file examples to compile the program.
	The way to compile the program depends on: (i) the compiler you use and (ii) if you want to
	use OPENMP multithreading directives. Next you will find some source compilation example
	command line. In the examples we have used MinGW compiler. But you can use another make
	and g++ distribution and specify the path in the calling.
		Using ming32-make with only ami_bmp (bmp) and without openmp
			C:\MinGW\bin\mingw32-make.exe -e CXX= C:/MinGW/bin/g++.exe
		Using ming32-make with only ami_bmp (bmp) and with openmp
			C:\MinGW\bin\mingw32-make.exe -e CXX= C:/MinGW/bin/g++.exe e OMPD=-DAMI_OMP_H -e OMPF=-fopenmp
		Using with the make and compiler added in the system path 
		with openmp and ami_bmp(bmp)
			make -e CXX=g++ e OMPD=-DAMI_OMP_H -e OMPF=-fopenmp

	IMPORTANT: If the next error appears during the compilation procedure:
	undefined reference to __sync_fetch_and_add_4
	You have to add in the make line the next option: -e ARCH=-march=i586, for example:
	make -e CXX=g++ e OMPD=-DAMI_OMP_H -e OMPF=-fopenmp e ARCH=-march=i586

1.1.3- Linux
	The project has a GNU makefile. To compile the project, we have to open a console
	and go to the directory where you have decompressed MorphologicalSankes zip file. Next you
	go to the source directory. (your_path/MorphologicalSnakes/source).
	According with the compiler you use and if you want to use OPENMP multithreading directives
	you have to use different way to compile. Next you will find some source compilation options,
	we suppose you have installed make and g++ in usr/bin, but you can use another make and
	g++ distribution and specify the path in the calling.
		Using make, openmp and ami_bmp (bmp)
			usr/bin/make -e CXX= usr/bin/g++ e OMPD=-DAMI_OMP_H -e OMPF=-fopenmp
		Using make with ami_bmp (bmp) and without openmp
			usr/bin/make -e CXX= usr/bin/g++
		Using with the make and compiler added in the system path and ami_bmp (bmp)
			make -e CXX=g++
			
	IMPORTANT: If you have an error during compile procedure like this:
	undefined reference to __sync_fetch_and_add_4
	You have to add in the make line the next option: -e ARCH=-march=i586 , for example:
	make -e CXX=g++ e OMPD=-DAMI_OMP_H -e OMPF=-fopenmp e ARCH=-march=i586

* Running instructions *
The executable generated is in the source directory. We go to
your_path/MorphologicalSnakes/source, and there we can find morphological_snake.exe,
thats the program that well use. To run it, we only type morphological_snake and the
parameters that will be detailed below.
2.1 Parameters
	In the next table we present the Morphological snakes function parameters. To
	identify the parameters we use a parameter option identifier before parameter value.
	Parameter 		  								Option	Needed
	Input image file 								-I 		Yes
	Output image file 								-O 		Yes
	Input contours file 							-C 		Yes
	Output contours file 							-F 		Yes
	Gaussian Standard Deviation 					-S 		No
	Snake type {expected values are 0,1 or 2} 		-T 		No
	Number of iterations 							-N 		No
	Snake ballon {expected values are -1,0 or 1} 	-B 		No
	Snake ballon difference radius 					-R 		No
	Edge detector threshold 						-P 		No
	Edge ballon threshold 							-E 		No

	You can pass the parameters in any order. In the case of ballon propagation, there are
	2 ways of performing it. The first one is to propagate the ballon while the image value is inside
	a given interval. The parameter -R is used to fit the interval radius. The second one is to
	propagate the ballon while there is not edge point found. The parameter E is used to fit a
	percentage of points that are considered as edge while ballon propagation.
	If a parameter is needed and the user does not provide it, the program will stop, and
	an error will be showed. On the other hand, for non-required parameters, a default value is
	assigned in the case user do not use them.

* Tools and libraries needed to compile and use the program *
All the libraries needed are included in the zip file.

* Files *
license.txt  License information
source->
	main.cpp                      Command line handler.
	Makefile                      Build configuration.
	make_samples.txt              Samples for different OS and configurations.
	mingwm10.dll		          Library needed to compile with gcc on Windows.
	pthreadVC2.dll	              Library needed to compile using OpenMP on Windows.
	WindowCompilationSample.bat   Samples for different configurations on Windows.
	WindowCompilationSample1.bat  Samples for different configurations on Windows.
	filters->			          Filters used in morphological snakes algorithm such as line opening, gauss convolution, etc..
	image->                       Libraries needed to read/write images.
	primitives->				  Class to manage 2D points.
	samples->					  Samples of use.
	snakes->                      Base morphological snakes algorithm.
	Ulibs32->					  Compiled libraries needed to read/write images on Unix 32 bits.
	Ulibs64->	                  Compiled libraries needed to read/write images on Unix 64 bits.
	utilities->					  Functions to manage pixel neighborhood.
	Wlibs->                       Compiled libraries needed to read/write images on Windows.
	
		
