% Automatic Lens Distortion Correction Using One Parameter Division Models

# ABOUT

* Author    : Miguel Alemán-Flores  <maleman@ctim.es>
              Luis Álvarez  <lalvarez@ctim.es>
              Luis Gómez <lgomez@ctim.es>
              Daniel Santana-Cedrés <dsantana@ctim.es>
* Copyright : (C) 2009-2013 IPOL Image Processing On Line http://www.ipol.im/
* License   : CC Creative Commons "Attribution-NonCommercial-ShareAlike" 
              see http://creativecommons.org/licenses/by-nc-sa/3.0/es/deed.en

# OVERVIEW

This source code provides an implementation of a lens distortion correction algorithm 
algorithm as described in IPOL

http://www.ipol.im/pub/algo/****

This program reads an input image and automatically estimates a 1 parameter 
division lens distortion model that it is used to correct image distortion. 

The programs produces 4 outputs: 
   (1) The estimated distortion parameter. 
   (2) An output image with the results of Canny Edge Detector.
   (3) An output image with the estimated distorted lines.
   (4) An output image where the distortion model is applied to correct the 
       image distortion. 

# REQUIREMENTS

The code is written in ANSI C, and should compile on any system with
an ANSI C compiler.

The libpng header and libraries are required on the system for
compilation and execution. See http://www.libpng.org/pub/png/libpng.html

MacOSX already provides libpng in versions before Montain Lion.
However, if you have problems with png library, you can follow the next steps:
	- Install Hombrew (http://brew.hs) and run the commands:
		* brew doctor
		* brew update
		* brew install libpng
		* brew link libpng --force


# COMPILATION

We have checked our code on:
	- Fedora 11 (Leonidas) with GCC version 4.4.1-2
	- Ubuntu 14.04 LTS (trusty) with GCC version 4.8.2
	- Windows 7 with Cygwin 6.1 and GCC version 4.8.2
	- MacOSX 10.6.8 (Snow Leopard) Darwing Kernel version 10.8.0 wiht GCC version 4.2.1

For compiling, simply use the provided makefile, with the command `make`.
If you want to use the OpenMP library, please use `make OMP=1`.

Alternatively, you can manually compile
		g++ -Wall -Wextra -O3 lens_distortion_correction_division_model_1p.cpp 
		ami_primitives/subpixel_image_contours.cpp ami_lens_distortion/lens_distortion_procedures.cpp 
		ami_primitives/line_extraction.cpp ami_lens_distortion/lens_distortion_model.cpp 
		ami_primitives/line_points.cpp ami_image/io_png/io_png.cpp ami_lens_distortion/lens_distortion.cpp 
		ami_utilities/utilities.cpp ami_pol/ami_pol.cpp -lpng -lm -o lens_distortion_correction_division_model_1p

		Or the following alternative compilation line for using the OpenMP library
		
    g++ -Wall -Wextra -O3 -fopenmp lens_distortion_correction_division_model_1p.cpp 
		ami_primitives/subpixel_image_contours.cpp ami_lens_distortion/lens_distortion_procedures.cpp 
		ami_primitives/line_extraction.cpp ami_lens_distortion/lens_distortion_model.cpp 
		ami_primitives/line_points.cpp ami_image/io_png/io_png.cpp ami_lens_distortion/lens_distortion.cpp 
		ami_utilities/utilities.cpp ami_pol/ami_pol.cpp -lpng -lm -o lens_distortion_correction_division_model_1p

# USAGE

This program takes 9 parameters:
“exe_file  input.png output_canny.png output_hough.png output_corrected_image.png high_threshold_Canny initial_distortion_parameter final_distortion_parameter distance_point_line_max_hough angle_point_orientation_max_difference primitives_file” 

* 'exe_file ' 		                        : exe file (called lens_distortion_correction_division_model_1p) 
* 'input.png'                             : input image
* 'output_canny.png'                      : output image wiht the detected edges by means of Canny method
* 'output_hough.png'                      : output image with the detected lines by means fof improved Hough transform
* 'output_corrected_image.png'            : output image with the corrected distortion
* 'high_threshold_Canny'                  : float value for the high threshold of the Canny method (between 0.7 and 1.0)
* 'initial_distortion_parameter'          : float value for the initial normalized distortion parameter (greater or equeal to -0.5)
* 'final_distortion_parameter'            : float value for the final normalized distortion parameter (greater or equal to the initial value)
* 'distance_point_line_max_hough'         : maximum distance allowed between points and associated lines
* 'angle_point_orientation_max_difference': maximum difference (in degrees) of the point orientation angle and the line angle
* 'primitives_file'                       : output file for saving information about the detected primitives using the improved Hough transform

# SOURCE CODE ORGANIZATION

The source code is organized in the following folders : 

* 'ami_pol' 		        : polynomial roots computation library.
* 'ami_filters' 		    : basic image filters including Gaussian convolution, gradient, 
					                Canny edge detector, etc.
* 'ami_image'			      : objects and basic methods to manage images.
* 'ami_image_draw'		  : basic procedure to draw primitives in an image.
* 'ami_lens_distortion'	: objects, methods and procedures to manage lens distortion models.
* 'ami_primitives'		  : basic objects and methods to manage primitives (lines and points)
* 'ami_utilities'		    : some auxilary macros and functions.
* 'documentation'       : doxygen documentation of the code in html format 
* 'example'             : result example for the pattern.png image with the parameters of the example command

# EXAMPLE

You can test the program with the provided test image (example/pattern.png) in the 
following way:

./lens_distortion_correction_division_model_1p example/pattern.png pattern_canny.png pattern_hough.png pattern_corrected_image.png 0.8 0.0 1.0 3.0 2.0 primitives.txt

Furthermore, you can compare your results with the results present inside the folder 'example'