=======================================================================
Separable image resampling for Optics Geometry Correction, version 1.5
=======================================================================

Authors: Bronislav Přibyl, xpriby12@stud.fit.vutbr.cz
         Michal Seeman, seeman@fit.vutbr.cz
         Pavel Zemčík, zemcik@fit.vutbr.cz
         
				 Brno University of Technology
				 Faculty of Informatics
				 Department of Computer Graphics and Multimedia

Description:
	This program has been developed to simulate image resampling algorithm which is beeing implemented in FPGA. However it is fully capable to resample an image. It uses Digilib library to operate easily with standard image formats, such as jpg or tif. Interpolation algorithm, which is kernel of this program, was primarily developed to resample biomedical images which are often affected by smooth barrel distortion caused by sensing lenses. Because of this, this program is not designated to correct strong geometric distortions. The input image is virtually split up into matrix of squares. Each square has its own coefficient set and is resampled independently in vertical and horizontal direction. Vertical and horizontal resampling is separable in this case which allows the algorithm to be very simple and therefore fast.
	
Version history:
1.5 - 2009-02-02
		- Bit-precise simulation of FIFO usage in horizontal resampling
		- FIR filter length increased from 7 to 8 pixels to better aproximate HW
		- Square coefficients in file canon.txt fixed
1.4 - 2008-06-16
		- Simulation of cyclic addressing: when FIR filter is out of image, it "overflows" to the opposite border of the image instead of producing black pixel
1.3 - 2008-05-18
		- Wrong indexing of FIR filter fixed
		- Bit-precise simulation of algorithm implemented (using long int (32 bit) as fixed point numeric format; upper 16 bits integer part, lower 16 bits fractional part)
1.2 - 2008-05-14
		- Values of coefficients DC0 and DR are now relative to the number of 1. Example: old DC0 = 1.35, new DC0 = 0.35; old DR = 0.91, new DR = -0.09. This is because prepared bit-precise simulation of algorithm.
		- Value of variable S is now relative to position in the output image. Example: position 97 / old S = 101.93, new S = 4.93; position 41 / old S = 35.11, new S = - 5.89. This is because prepared bit-precise simulation of algorithm.
    - small bugfix in procedure "resample_1d_y" in module "resample.c"
1.1 - February 2008
		- Coefficients and variables renamed according to current development phase
        - s0     -> S0
        - dxs0   -> DC0
        - dys0   -> DR
        - dxys   -> DDC
        - sStart -> SoR
        - dxs    -> DC
        - s      -> S
    - Precision decreased from long double to float (no impact on results)
    - Minor speed improvement
    - Minor code cleanup
1.0 - December 2007
		- Initial release

Environment:
	- platform: Linux (tested on Ubuntu 8.10)
	- compiler: gcc (compiled with gcc version 4.3.2)
	- Digilib library (dynamic linked library - DigILib.so)

Input:
	- input image - image to be resampled (jpg or tif)
	- coefficient set - text file with coefficients (for format of this file see Manual section of this document)

Output:
	- output image - resampled image (jpg or tif)


Installation and usage:
	- installation: no need
	- compilation: type "make" in the directory with Makefile (edit compiler flags in Makefile if needed)
	- example of use: ./resampling ./demo/plank_def.jpg ./demo/plank_out.jpg ./demo/canon.txt (Corrects optical distortion in plank_def.jpg caused by some certain Canon objective, producing plank_out.jpg; Note that plank_out.jpg should be the same image as plank_cor.jpg.)


Format of coefficient set (for example see squares.txt):
--- BEGIN ----------------------------------------------------------------------
square-size:
<size_of_square(integer)>

<some_white_space>

squares:
<number_of_squares_horizontally(integer)>;<number_of_squares_vertically(integer)>

<some_white_space>

<S0.x(float)>:<S0.y(float)>;<DC0.x(float)>:<DC0.y(float)>;<DR.x(float)>:<DR.y(float)>;<DDC.x(float)>:<DDC.y(float)>
...
{repeat_for_each_square}

--- END ------------------------------------------------------------------------

Note: for information about meaning of coefficients, see bachelor's thesis of Bronislav Přibyl: Image Processing in FPGA: Separable Image Resampling. Brno University of Technology, Faculty of Information Technology, Department of Computer Graphics and Multimedia, 2008.



List of files included in the archive:
  - demo/canon.txt
  - demo/chess_cor.jpg
  - demo/chess_def.jpg
  - demo/plank_cor.jpg
  - demo/plank_def.jpg
  - digilib/DigILib.so
  - digilib/Image.h
  - digilib/ImageFil.h
  - digilib/LibEntry.h
  - bit-handling.c
  - bit-handling.h
	- FIR.c
	- FIR.h
	- Makefile
	- readme.txt
	- resampling.c
	- squares.c
	- squares.h

