INTRO
-----

These utilities work on the raw .cam format file (Hawaii chip raster) and corresponding tiffs.

* cam2tiff re-arranges the pixels from the IR camera into a tiff. It also prints statistics about the pixels.

* gencamtest generates tests files for cam2tiff: quadrants, gradients, lines, noise etc. (make example_files)

* getpixel extracts a given pixel addressed by {quadrant, x, y} wrt Hawaii chip, in the format 0xffeedd (from either .cam or .tiff file)

* cam2dat extracts the pixels from the IR camera into a 4-column ascii data file. (Useful for fftplot etc). 
* dat2cam is the reverse of cam2dat.

* beamfinder searches a tiff for candidate beams, and prints their coordinates.

Invoke programs with -h  for more info.
In particular, cam2tiff -h   prints out a description of the input byte format and raster pattern.


COMPILE
-------

make; sudo make install

Need to have installed: libtiff3-devel (or libtiff4-dev)
		      : python, ipython, python-imaging, python-numpy, python-scipy, python-matplotlib

Ensure the Python-Imaging-Library fix is applied (see below)


VIEWING TIFF FILES
------------------

 * display (part of ImageMagick) works (and can cope with 32-bit tiffs), and shows lots of info. Middle-click for pixel info. Note quantum!
 * qiv can do it (and is the fastest), but fails on 32-bit tiff.
 * eog works, but remember to turn off interpolation on zoom.
 * xli can't do it.
 * gimp is the only program which can attempt to display corrupt tiff files (Gimp treats 32-bit tiff as RGBA, wrongly)

Checking pixel values can be done with either:

 * qiv and kcolorchoooser    #both of these only work at 8-bit, so
 * gimp			     #there's no easy way to see the Least Significant Byte
 * xxd			     #this is doing it the hard way!
 * od -D		     #view raw data.
 * display		     #middle-click pixel (Note quantum-depth...)
 * stream		     #Extract pixel values. (Or, use getpixel)


SEE ALSO
--------

Libtiff, libtiff-tools aka libtiff-progs, imagemagick/convert
In particular, "tiffcp -b" allows subtraction of one tiff from another.
Also, "stream" (part of imagemagick) allows direct reads of specified pixels.

An alternative would be to use the FITS tools:	https://www.cfa.harvard.edu/~john/funtools/


IMAGEMAGICK
-----------

ImageMagick (convert/display/stream) can cope with 32-bit greyscale tiffs. BUT, the quantum defaults to 16-bit, so it will
only pay attention to the 2 MSBytes, ignoring the others. This results in wrong pixel information being displayed, wrong data out
by stream, and inability to enhance very dark images. For example, a tiff containing bytes "00 50 51 52" (little endian) will be displayed/streamed
as if it contained "51 52 51 52", thus losing the LSBytes' information.

To fix this, rebuild it using ./configure --with-quantum-depth=32
   (also need libtiff4-dev installed)

Eg:
 *  display  file.tiff
 *  stream -verbose -storage-type integer file.tiff pixels.dat	#output a series of integers.
 *  stream -storage-type integer -colorspace gray -depth 32 -map i -extract 1x1+0+0 file.tiff pixel.dat  #extract exactly one pixel

The script: check_imagemagick_quantum.sh (part of 'make install') verifies this.


PYTHON IMAGING LIBRARY
----------------------

The Python Imaging library is used by beamfinder to support directly opening TIFF files, rather than
having to first extract the file with "/usr/local/bin/stream -map i -storage-type quantum -depth 32 test.tiff test.raw"

BUT, it is missing a definition for 32-bit monochrome TIFFs: http://www.mailinglistarchive.com/html/image-sig@python.org/2011-04/msg00009.html
To fix this, patch the installed packages manually. (The patch is applied upstream; this may not be required on later packages).

* On Ubuntu Lucid, edit:
	/usr/lib/python2.6/dist-packages/PIL/TiffImagePlugin.py
  and insert the line:
	(II, 1, 1, 1, (32,), ()): ("I", "I;32N"),
  above this one:
        (II, 1, 2, 1, (32,), ()): ("I", "I;32S"),


* On Mandriva 2009.1, edit:
	/usr/lib/python2.6/site-packages/PIL/TiffImagePlugin.py
  and insert the line:
	(1, 1, 1, (32,), ()): ("I", "I;32N"),
  above this one:
	(1, 2, 1, (32,), ()): ("I", "I;32S"),


BUT....Python still can't correctly read 32-bit tiffs: it erroneously interprets the unsigned values as signed! 
So, use the C-implementation beam_finder.c instead.


ENDIANNESS and BITS
-------------------

* The raw output from the ADC is a 24-bit sample (containing about 19 bits of real signal, and 5 of noise). This is stored in a uint32.

* This is stored directly in the .cam file. It's Intel native (little endian), so is L:M:H:0   (i.e. highest byte all zero).

* The tiff format is big-endian (standard for tiff), and has been left-shifted by 8 bits (so that the lsb is zero) in order to make it display sensibly.


FILE FORMATS
------------

See cam2tiff -h for the ordering. A brief summary:
 - Cam format uses a raster, starting in bottom left, moving right, then up. (4 quads are interleaved).
 - Tiff format merges all 4 quads to a single image, and follows the X convention of origin top-left.
 - Looking at the .cam files with xxd is occasionally useful. Don't attempt this with the .tiff: it isn't very helpful Extract pixels with 'stream' or 'getpixel' instead.
