HAWAIISIM

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

NAME

hawaiisim - Simulate IR Camera hardware

SYNOPSIS

Hawaiisim simulates the physical hardware (the Hawaii chip, the optics, and the ADC), so as to verify the PulseBlaster programs, and to test the toolchain.

DESCRIPTION

INTRODUCTION:
        Hawaiisim simulates the Rockwell Hawaii_25 chip and the NI4462 ADC converter hardware,

        using a PulseBlaster replay log (.pbsim) file. The simulation file contains the sequence of

        control-data timings written to the virtual hawaii. The resulting output data is a series

        of analog readings taken from the virtual hawaii chip, clocked by the pbsim file, and exposed

        to light/glow/noise at a certain rate. Hawaiisim also carefully verifies that all clock

        pulses are legal (eg no counter overflows, min-lengths satisfied, no read during reset, no

        adc with read disabled etc). The particular wiring of the Hawaii chip is #define'd to

        correspond to the physical wiring in the dewar. Copyright Richard Neill, 2011-2013, GPL3+.

        This is useful for several purposes:

          - Validation of pulseblaster programs.

          - Checking which pixels are read/reset (address, count, sequence).

          - Checking whether the program is mains-synchronous.

          - Simulating image generation for analysis.

NOTE:
        The real hardware uses an NI4462 ADC, which begins acquisition of many samples when triggered by ADC.

        It's more helpful to simulate a FAKEADC which does exactly ONE conversion, on every falling-edge of

        the FAKEADC bit. Multiple-reads must be explicit in the replaylog.

EXAMPLE:
        hawaiisim -i frame-reset-read.pbsim -o tmp.cam -e glow -L 0.5 -r noise;

        cam2tiff tmp.cam tmp.tiff; display tmp.tiff

        This replays a full-frame pattern, simulates the exposure, and draws the image.

        See: /usr/local/share/doc/hawaiisim/ for example files.

USAGE:  hawaiisim  [options] -i LOGFILE.pbsim -o OUTPUT.dat

OPTIONS:
        -h, --help              Show help

        -i  INFILE.pbsim        Input File. (required, except with -t)
        -o  OUTFILE.dat         Output File (otherwise, infile, renamed with .dat)  Or /dev/null.

        -t                      Test mode. Ignore infile; output a full-array image in .cam format.
                                Reset for 1.50 us, expose for 7500.00 ms, do ADC for 1310.72 ms.

        -d                      Debugging on (very verbose).
        -c                      Continue on error, don't exit immediately. (Eventually, exit 1).
        -q                      Quieter: don't print pixel addresses for reads/resets (also faster).
        -x                      Allow overwrite of existing output file (also, don't enforce file-extensions).

        -a  ADC_MODE            ADC simulation model: ideal | noise | hum
              ideal   [default]   ADC reads perfectly.
              noise               Each ADC read has thermal noise, mean 400.00 electrons.
              hum     [best]      Thermal noise (400.00 e) and 50.00 Hz mains hum (500.00 electrons).

        -r  RESET_MODE            Reset model: zero | const | noise | expon
              zero    [default]   Reset is perfect, to exactly zero.
              const               Reset is perfect, to level 1000 electrons.
              noise               Reset to constant 1000 with thermal kTC noise 250.00 electrons.
              expon   [best]      Cells decay exponentially towards level 1000, with
                                  time-constant 0.50 us and thermal noise 250.00 electrons.

        -e  EXPOSURE_MODE       Exposure model: debug | uniform | glow | debug:file | linear:file | image:file
             debug                Pixels are set to own address (quad:row:col) + noise in lsb.
             uniform  [default]   Uniform, linear exposure at 1.60 electrons/us. No noise.
             glow                 Linear (1.60 e/us), with glow and background (0.01 + 0.02 e/us).
             debug:FILE           Pixels are set to the exact value from FILE (no integration).
             linear:FILE          Linear exposure, pixels from FILE. White pixels are 1.60 e/us.
             image:FILE  [best]   Exposure from file (1.60 e/us) with glow, background (0.01 + 0.02 e/us).
                                To create a correctly formatted image FILE.tiff, use gencamtest/cam2tiff.

CONFIGURATION OPTIONS:         (changes to the default values)
        -A  ADC_R_NOISE         Set ADC read (resistor) noise std-deviation. Default: 400.00 electrons.
        -H  HAWAII_C_NOISE      Set Hawaii thermal (capacitor-reset) noise. Default: 250.00 electrons.
        -R  RESET_LEVEL         Set Hawaii reset level. Default 1000 electrons.
        -T  RESET_TIME_CONST    Set Hawaii reset time-constant (for -r expon). Default: 0.50 us.
        -G  GLOW_LEVEL          Set Hawaii source-follower glow level (shot-noise). Default 0.01 e/us.
        -B  BACKGROUND_LEVEL    Set Hawaii background 'glow' level (shot-noise). Default 0.02 e/us.
        -L  LIGHT_LEVEL         Set illumination level (shot-noise mean). Default 1.60 e/us.
        -I  IMAGE_LEVEL         Set image level for a white pixel. (shot-noise). Default 1.60 e/us.
        -E  TEST_EXPOSURE_LEN   Set exposure length in test (-t) mode. Default 7500000.00 us.
        -F  TEST_RESET_LEN      Set reset length in test (-t) mode. Default 1.50 us.
        -V  MAINS_HUM_LEVEL     Set mains hum amplitude. Default: 500.00 electrons.
        -W  MAINS_HUM_FREQ      Set mains hum frequency. Default: 50.00 Hz.

PHYSICS MODEL:
        Each array pixel is considered to be a uint_24, the same as the ADC output. We use integer

        values, and work in electrons (rather than photons) for convenience. The ADC is configured

        such that 1 ADC_level = 1 electron = 1 unit. Adding light increases the value. Conversion

        of float -> int is dithered, so summing exposures over short intervals integrates correctly.

        Pixel voltages are int_32, so can temporarily exceed the range (eg reset + negative noise).

        RESET causes the pixels in that row to decay exponentially (with a very short time-constant)

        towards the level at which they are biased. Thermal capacitor-reset noise 'HAWAII_C_NOISE'.

        is added. (The physics model can be changed with -r, and the parameters by -R/-T; the best

        'real-world' model is '-r expon').

        ADC reads obtain the pixel value, with thermal (resistor) noise 'ADC_R_NOISE'. Multiple

        reads reduce the noise by SQRT(n). The mains-hum noise has amplitude 'MAINS_HUM_LEVEL', and

        frequency 'MAINS_HUM_FREQ'. The ADC is constrained to the range [0,0xffffff]; values outside this

        will clip. (The physics model can be changed with -a, and the parameter by -A; the best

        'real-world' model is '-a hum'). Also, the 'FakeADC is an ideal, virtual ADC that makes a single

        conversion exactly when triggered, the real-world ADC has all sorts of 'quirks' including a

        variable delay for triggering, and convolution between adjacent (multiplexed) samples.

        ILLUMINATION/Exposure to light exposes the array to a certain number of photons (electrons)

        proportional to the brightness and the time. These arrive according to the shot-noise model.

        The array may be illuminated uniformly, or the illumination pattern specified by a TIFF.

        Glow noise and Background noise (shot-noise) are added; glow depends on the output-follower

        There is NO thermal noise added by illumination: an isolated capacitor cannot spontaneously

        alter its charge; also the total of such noise would depend on the mathematical exposure

        interval, dt ! (The physics model can be changed with -e, and the parameters by -G/-L/-I;

        the best 'real-world' model is '-e glow' or '-e tiff:file').

        Noise is modelled as thermal noise or shot noise or mains hum.

         * THERMAL NOISE is Gaussian, mean=0, and is used for ADC_R_NOISE and HAWAII_C_NOISE.

           Capacitance-reset noise is incurred by Reset; thermal resistance noise by ADC conversion.

         * SHOT NOISE is Poisson, always > 0, and is used to model incoming light for exposure: i.e.

           GLOW_LEVEL (zero, unless the output-follower is read-enabled), BACKGROUND_LEVEL, and

           LIGHT_LEVEL / IMAGE_LEVEL. This smooths-out over long (or sum of short) exposures.

           For Resistor and Capacitor noise models: http://en.wikipedia.org/wiki/Johnson–Nyquist_noise .

         * MAINS HUM is ideal: MAINS_HUM_LEVEL * cos(2*PI*MAINS_HUM_FREQ). Harmonics and spikes not

           included. Ideally small, given tri-axial cable and battery-powered earth-loop avoidance.

        IMPERFECTIONS in the model:

         * In the model, pixels reset to zero, and fill towards 0xffffff. In the real device, reset

           charges the FPA and photons discharge each cell towards zero.

         * The ADC range is defined as [0,0xffffff]; it maps exactly to full-scale without headroom.

         * Glow is uniform, but the Hawaii's Glow originates from the source followers in the corners.

CIRCUIT WIRING CONFIGURATION:
        This is the 'wiring' between the Hawaii array and the individual bits of the PulseBlaster,

        #define'd to match the circuit in the dewar. Only the lowest 24 bits are used. Some lines

        are commoned across quadrants: (READ,RESETB,LSYNC,FSYNC).

          BIT           FUNCTION        EXPLANATION

          ---           ---------       -----------

            0           PIXEL   0       These clock the horizontal (x,column,fast) register on

            1           PIXEL   1       either edge; even-numbered(**) columns are selected after a

            2           PIXEL   2       positive edge; odd colums after a negative edge.

            3           PIXEL   3       [Must be low when LSync is low.]

            4           LINE    0       These clock the vertical (y,row,slow) register on either

            5           LINE    1       edge; even-numbered rows(**) are selected after a positive

            6           LINE    2       edge; odd rows after a negative edge.

            7           LINE    3       [Must be low when LSync is low.]

            8           READ   all      Active high enables output follower; low minimises glow.

           12           RESETB all      Active low to reset the currently selected rows.

           13           LSYNC  all      Active low to reset the column register on all quadrants.

           14           FSYNC  all      Active low to reset the row register on all quadrants.

           15           ADC             Trigger the real NI4462 ADC on a falling edge.

           23           FAKEADC         Trigger the FAKEADC to take one sample on a falling edge.

        Pulse length requirements are configured as:

         * Any line:    minimum pulse (either phase):    100 ns

         * Reset line:  minimum pulse:                   500 ns

         * ADC line:    minimum pulse:                   50 ns

         * Fake_ADC:    minimum pulse:                   2500 ns

         * Fake_ADC:    setup/hold times:                5000/2500 ns

         * Fake_ADC:    minimum interval for retrigger:  2500 ns

        (**) Note: the Hawaii docs count from 1..512; we count 0..511.

ORDERING OF PIXELS AND QUADRANTS:
        The Quadrant/Pixel/Raster orientation in the Hawaii documentation; also in `cam2tiff -h`.

        Quadrants 0,1,2,3 are BR,BL,TL,TR. Quadrant origin is bottom left: x moves right; y up.

         * ROW    = y (or c) = slow-direction, controlled by LINE / FSYNC. (RESETB is whole row).

         * COLUMN = x (or r) = fast-direction, controlled by PIXEL / LSYNC

        Row is more significant than column, hence co-ordinates are listed as (y,x).

        The input TIFF file (used by -e tiff:file) is a standard 1024 x 1024 32 bit greyscale image.

        Similarly to cam2tiff, it is 'the right way up', (even though X11's conventions have the

        origin top-left, with y downwards.). The LSByte of the TIFF is ignored; the 3 MSB control

        the output (such that 0xffffff or white is worth 1.60 e/us.)

        Each ADC read results in a stream of 4 words (intel le_32 byte-order) for Q0,Q1,Q2,Q3.

        If the entire array is raster-scanned once (eg -t), the result will be a valid .cam file.

        Otherwise, the output will be a stream of 16-byte groups: use the .dat extension for the output.

        The Hawaii chip has 512 rows/columns per quadrant, addressed as 0...511. After reset (LSync/FSync),

        before the first clock-edge (Pixel/Line), no pixel is connected to the output. Clocking beyond

        the end is technically ok, but more than one off the end (512) is considered an error. Likwise,

        reading from a disconnected row/column (off the end, or not at the beginning) triggers an error.

STREAMS:
        * The simulated ADC data is written to outfile. This is in the .cam format (use cam2dat to convert).

        * The pixel addresses of reads/resets are sent to STDOUT (unless -q).

        * Errors (and debugging info, if -d) go to STDERR.

EXIT STATUS:
        0 on success, 1 on error.

AUTHOR

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