CAM2TIFF

Section: User Commands (1)
Updated: July 2012
Index Return to Main Contents

NAME

cam2tiff - convert a cam file to a tiff file, calculate statistics

SYNOPSIS

This converts the multiplexed raw data from the IR camera into a TIFF file.
Read data file data.cam, and generate an image, output.tiff. (This is lossless).
Quadrant de-multiplexing is performed; invoke with -h for a diagram and explanation.
Statistics (mean and variance) are printed for each quadrant, and overall.

DESCRIPTION

cam2tiff converts the data file from the IR camera into a tiff file.

USAGE:    cam2tiff [OPTIONS] input.cam output.tiff           #Not stdin/stdout.
OPTIONS:     -h, --help        show help
              -c,-W    COLS     number of columns (width) for each quadrant. Default: 512
              -r,-H    ROWS     number of rows (height) for each quadrant. Default: 512

The camera contains 1024x1024 pixels, arranged in 4 quadrants of 512x512 pixels.
These quadrants are Q0,Q1,Q2,Q3 (alternatively labelled 1,2,3,4) positioned as
Q0=bottom_right. Q1=bottom_left, Q2=top_left, Q3=top_right.

The input.cam file is a 4 MByte file (4 quadrants, each 512x512 pixels; 4-Byte words).
The data is an interleaved stream of pixels from each quadrant in turn (0,1,2,3).
A pixel is a 24-bit ADC result (~ 19:5 bits signal:noise), in the 3 LSB of a little-endian uint32.
Thus the byte order is: Q0_L:M:H:0, Q1_L:M:H:0; Q2_L:M:H:0; Q3_L:M:H:0.

These 4 words form an interleaved raster, scanning left->right (fast) and bottom->top (slowly).
cam2tiff re-arranges this muddle into a single 1024x1024 pixel, 32-bit greyscale TIFF file,
with Q0 in the bottom right. For displayability, bytes are left-shifted: LSByte is zero.
Here is a diagram; see the file 'llcpad.html' in the Hawaii documentation for a better one:

   (y)     +---------------------+
           |          |         z|        Pixels are read in the order
    s ^    |          |          |        abcdefgh...pqrs...z
    l |    |    Q2    |    Q3    |
    o |    |r         |s         |        Slow scan, fast scan refer to the
    w |    |cg        |dh        |        clocking of the HAWAII chip.
      |    |----------+----------|        The fast scan (column / x) direction
    s |    |          |          |        is controlled by PIXEL_CLOCK;
    c |    |          |          |        the slow scan (row / y) direction
    a |    |    Q1    |    Q0    |        is controlled by LINE_CLOCK.
    n |    |q         |p         |
           |bf        |ae        |        The output TIFF has the same
           O---------------------+        orientation as the Hawaii chip.
                                          But note that X11 considers (x,y) as
                 --------->               the directions (right,down).
                  fast scan  (x)

The orientation of the .cam file (and the TIFF on screen) have the origin (O) in the bottom left,
(i.e. x-axis (col) points to the right, and y-axis (row) points upward; Q0 is in bottom right.)
It is displayed on screen this way too. However, the X11 convention is that the origin is top-left,
the x-axis points right, and y-axis points down. [Both conventions are 0-based. So, pixel co-ordinates
as show by 'display', or used to specify geometry for 'stream' differ from Hawaii co-ordinates.
To transform from one co-ordinate system to the other, use: x' = x ; y' = (1023 - y) .
If only a sub-array of the chip is being read out, use -r, -c to override the default array-size.

Statistics: mean, std-dev (population), number. These are calculated for each quadrant, and overall.
Exit codes: 0 on success; 1 on failure; 2 on error from which some data was recovered.
Viewing/processing 32-bit tiffs: use 'display'/'stream'; see also tiffcp. Currently, all of gimp, eog,
qiv fail on 32-bit images. NB, build ImageMagick --with-quantum-depth=32.

AUTHOR

The author of cam2tiff and this manual page is Richard Neill, <cam2tiff#AT(spamblock)#richardneill.org>
Copyright July 2012; this is Free Software (GPL v3+), see the source for copying conditions.