file:    README
authors: Ting-Jen Yen and Chee Yap
		{yentj,yap}@cs.nyu.edu
	Department of Computer Science
	Courant Institute of Mathematical Sciences
	New York University
date:   September 6, 2000

============================================================
This directory contains C/C++ programs for subpixel
transformation of images in tiff format.  The two main programs
are called "disc" and "bilinear".  The latter is an implementation
of the well-known bilinear interpolation method.

For more information about these programs, see our
visualization project page at NYU
	http://cs.nyu.edu/visual/
click under "projects-->image tools-->geometric transforms".

============================================================
Files:
  *.c, *.C: 	source files.
  map*.tiff:	image files
  Makefile:	useful targets for compiling and testing our programs.

	(1) make: The default target is to make the executables
		(disc, bilinear, table, extract).
		Make sure that your LD_LIBRARY_PATH includes
		the tiff libraries.
	(2) make timing: this compares the running times of the bilinear
		and disc programs.  Basically, the latter is 3 times slower.

  disc:  Executable program to transforms an input image using a
	 geometric interpolation method based on a unit area disc
	 shape (it uses the table.bin file for table lookup).

	 Usage:  disc [-n] input-file  output-file  factor

 	   where the size of the output-file will be enlarged by
	   an order of "2^factor".  For example, if factor=3, then
	   an nxm image produce an 8n x 8m intermediate image.  
	   Current implementation restricts factor to be an integer
	   between 1 and 8, inclusive.  If the "-n" flag is set,
	   then the image will be shrunk back to original size by
	   simple averaging before it is written out.

  bilinear: Executable program to transform an input image using
	 bilinear interpolation.

	 Usage:  bilinear [-n] input-file output-file scale

	   where the arguments are as for "disc", except that "scale"
	   is any positive integer that plays the role of the
	   "2^factor" in "disc".

  table:  Executable to create a table for use by the disc program.
	  See explanation below.  It takes no inputs and produces
	  a file "table.bin".

  table.bin:  The output from the "table" program.

  extract:  This program is used for debugging purposes.
	   It extracts a weight vector (double[9])
	   corresponding to a point (x,y) within a pixel.
	   Currently, x and y range from 0 to 255, corresponding
	   to the size of table.bin.

	   Usage:   extract x-coordinate y-coordinate

============================================================
Images:

  map.tiff :  774x411 scanned map image.
  map0.tiff:  62x55 cropped image from map.tiff

  map1.tif:  Image created by "disc" from map0.tiff, using factor = 3.
  map2.tif:  Image created by "disc" from map1.tif, using factor = 3, 
	      with "-n" flag set.
  map3.tif:  Image created by "disc" from map2.tif, using factor = 3, 
	      with "-n" flag set.

  mapb1.tif:  Image created by "bilinear" from map0.tiff, with scale = 8.
  mapb2.tif:  Image created by "bilinear" from map1.tiff, with scale = 8 and -n flag
  mapb3.tif:  Image created by "bilinear" from map2.tiff, with scale = 8 and -n flag

============================================================
Note on Table Creation.
============================================================

We place the center of a disc with area 1 at
some floating-point coordinate (x,y), and calculate the area that
the disc overlap each grid square.  This area is the weight
assigned to this grid square.  Clearly, at most 9 grid squares
can overlap our disc.  These squares are numbered 0, 1, ..., 8
as shown in the figure below.  The center of our disc lies
somewhere in grid square 4.  

  ----------------------
  |      |      |      |
  |  0   |  1   |  2   |
  |      |      |      |
  -------+------+-------
  |      |      |      |
  |  3   |  4   |  5   |
  |      |      |      |
  -------+------+-------
  |      |      |      |
  |  6   |  7   |  8   |
  |      |      |      |
  ----------------------

To discretize our problem we assume that grid square 4 is subdivided
into 256x256 subpixels, and the center of the disc lies in the center
of one of these subpixels.  Our table stores for each subpixel,
a vector of 9 double values, corresponding to the the weights of
the 9 grid squares.

These precomputed weight vectors are stored in an array
of double[256][256][9], and written into the file "table.bin".


============================================================
Note on Timing 
============================================================
As the timing below shows, the program disc is roughly 3 times
slower than the program bilinear:
 
     > make timing
     > time ./bilinear -n map0.tiff tempmap1.tiff 8
     > Input image with 62x55 size (3 byte(s) per pixel)
     > 
     > real        1.1
     > user        0.6
     > sys         0.0
     > time ./bilinear map0.tiff tempmap2.tiff 8
     > Input image with 62x55 size (3 byte(s) per pixel)
     > 
     > real        1.6
     > user        0.7
     > sys         0.0
     > time ./disc -n map0.tiff tempmap3.tiff 3
     > Input image with 62x55 size (3 byte(s) per pixel)
     > 
     > real        3.3
     > user        1.9
     > sys         0.0
     > time ./disc map0.tiff tempmap4.tiff 3
     > Input image with 62x55 size (3 byte(s) per pixel)
     > 
     > real        4.4
     > user        2.0
     > sys         0.0
     >

