IMAN Image Analyzer - Old Info

Jack Baldwin 26 April 1999

with edits by

B. Gregory (29 Nov 1999)

M. Boccas (18 Aug 2000, 19 Dec 2000)

R.Cantarutti (30 Jan 2001)

 

1.0 INTRODUCTION

The image analyzer IMAN is integrated into the offset guider at the cassegrain focus of the 4m Blanco telescope. IMAN consists of four components:

• The IMAN OPTICS, which are part of the cassegrain guider;
• The IMAN CAMERA SYSTEM, which includes a CCD mounted inside the guider, an electronics box mounted on the outside of the guider, and the IMAN PC in the computer room;
• The IMAN REDUCTION SYSTEM, which runs on the IMAN SUN (currently CTIOt2); and
• The IMAN CONTROL SYSTEM, which is part of the TCS. This accepts commands from the telescope operator and then translates them into other commands which are issued to the optics, camera and reduction systems in the correct sequence.

IMAN is always available at f/8 and f/14. It can be used by the night assistant at any time. It writes its results into the log file /ut22/iman/iman.log. With easy-to-use TCS commands, the night assistant can take results from this log file and use them as input for adjusting the telescope optics.

2.0 OPTICS

The actual image analyzer is a 80 mm diameter x 200 mm long tube with a small CCD head mounted on the back. The tube fits inside the offset guider, in a space that was originally used for an image-dissector. Inside the optics tube is a collimator lens which views the telescope's focal plane, followed by a Shack-Hartmann lenslet array which reimages onto the CCD. This whole unit moves around with the guide probe; the CCD head includes only the CCD and a Peltier cooler, and is connected to an electronics unit mounted on the outside of the guider.

Light is fed into the image analyzer using the optical train originally intended to feed the image-dissector back in the days when it was the detector for the guider. Nowdays the detector for the guider is a CCD-TV system which is mounted on the outside of the offset guider shell, at a port originally intended for an eyepiece. A remotely movable pickoff mirror (the "flat mirror") can either divert light to the guider TV, or let it pass through to the image analyzer. A pellicle beamsplitter parallel and next to the flat mirror was installed (1998) and can be used: it will direct 10% of the light to the guider and 90% of the light to the image analyzer, allowing simultaneous guiding while running IMAN.

Figure 1 shows the light path. Light coming from the telescope's secondary mirror first strikes a 45-deg diagonal pickoff mirror, then arrives at the position of the movable flat mirror. When the flat mirror is moved out of the way, the light passes through a folding prism, then through an aperture which is in the focal plane of the telescope, and finally into the IMAN optics tube which contains the collimator, lenslet array and CCD. The aperture is on a 3-postion wheel. The normal observing position is a 2.0mm diameter (13 arcsec) hole. The other positions are a much larger (133 arcsec) hole, and a calibration position which consists of a pinhole with an LED behind it.

The calibration position feeds a perfectly spherical wavefront into the image analyzer. The collimator converts this into a plane wavefront which then strikes the lenslet array. Each lenslet converts the light incident on it into a point image on the CCD. Thus an array of spots is formed (Figure 2). An imperfect wavefront coming from a star follows the same path, but each spot is displaced from the calibration position by an amount proportional to the inclination of the wavefront at the lenslet (Figure 3).

Both the flat mirror and the aperture wheel are remotely controlled from the TCS. They can be operated from the IMAGE ANALYZER menu using the following commands:

CALIBRATION POSITION

LARGE APERTURE

SMALL APERTURE

OBSERVE POSITION (move flat mir to GDR, ap to SMALL, CAMERA OFF)

FLAT MIRROR (set to GDR or IMAN)

PELLICLE (set to IN or OUT)

or they can operated from the command window using the following commands:

3.0 IMAN CAMERA

3.1 General Description

The Image Analyzer (IMAN) uses an upgraded version of one of our CCD-TV camera systems. A larger format CCD, a 12 bit serial A/D converter, a new sequencer, and a Coreco video processor board running in a 486-66 computer, were adopted for the IMAN.

The CCD is a 770 x 1152 CCD used in frame transfer mode, effectively yielding a 770 (H) x 576 (V) format. Pixels are 22.5 x 22.5 microns. This is a thick, front illuminated device produced by EEV in England. The chip can be cooled down to about -35 C by way of a Peltier cooler. This CCD is used in multiple pinned phase (MPP) mode, and it can also be operated at room temperature. We have actually taken 30 second integrations and observed an increase in the background level of less than 5% of the full dynamic range (4096 counts) for the A/D converter, while running the CCD at dome temperature (8 C).

The data are digitized before leaving the electronics in the Cass Cage and are sent as a serial stream of bits -where each CCD pixel is represented by 12 bits- to the computer in the Console room. Software commands replace the former User-Interface (CEU) front panel switches. The new design of the sequencer is based on a Xilinx field programmable gate array (FPGA) and an extended set of commands is available to the software. The software also controls the Coreco board which gets used to both process and display data.

For the long integrations, the gain is set to about 50 e/ADU, so that the maximum count possible of 4095 (for the 12 bit A/D converter) represents somewhat less than the CCD full well condition.

3.2 Thermoelectric Cooler

The camera head is equipped with a Peltier cooler. The cooler generates about 16 watts while it is operating, which is an unfortunately large amount of heat to dump into the offset guider (it presumably leads to hot air bubbles going up the stovepipe baffle, directly through the telescope's lightpath). For this reason, the power to the camera and cooler assembly is remotely controlled from the console room, and is normally turned off except when an IMAN observation is being made. The CCD cools down almost instantly when the cooler power is turned on. This is an adequate level of heat control when IMAN is used only occasionally during the night.

However, IMAN is sometimes used all night long, such as when the sky is being mapped to prepare new lookup tables for the active optics. Under these conditions, it is more convenient to leave the camera power switched on all night. We have found that IMAN actually works fine when the CCD is used uncooled, at ambient nighttime temperature at least as high as 8°C. However, we don't know whether or not cooling will be needed on warm summer nights.

To give a choice about whether or not to use the cooler, the on/off switch on the camera electronics box (on the side of the instrument rotator) has three positions:

• Up = "ON (ALL)" -- camera power ON, cooler ON;
• Center = "OFF" -- camera power OFF, cooler OFF; and
• Down = "ON (NO TEC)" -- camera power ON, thermo-electric cooler OFF .

This switch should normally be in the "ON (NO TEC)" position (camera ON, cooler OFF). During the summer months the "ON (ALL)" position (camera ON, cooler ON) may be required to suppress hot pixels. The middle position (camera OFF) should never be used; the camera power is remotely controlled.

3.3 Camera Commands

These can either be typed in directly at the IMAN PC, or entered from the TCS Image Analyzer menu using the command "IMAN COMMAND TO PC", or entered in the TCS command mode (preceeding each command by "iman pc"; cf. type "iman pc histo").

3.4 IMAN Camera Restart Procedure

The IMAN PC should be restarted at the beginning of any night that IMAN will be used. This is the best way to ensure that the NFS link between the PC and the Sun will be working. To restart:

• The IMAN PC's monitor is at the far right end of the computer room, against the wall. It's keyboard is just to the left of the monitor.
• reboot the PC, by pressing the button marked "reset" on the PC front panel.
• type "gonfs". This should re-establish the link to IMAN SUN.

BUT...check to see if either of the following messages are buried in the lines of output written by gonfs:

"NSF216F-CTIO4m is not a PC-NFS authentication server."
or
"NSF216F-CTIO1m is not a PC-NFS authentication server."

If one of these messages appears, try reboot and gonfs one more time. If the message still appears, call the data system specialist, then go ahead and try the next step anyway... maybe things will work for a while.

• still on the IMAN PC, type "iman". The iman program should start up and give the message "OK".

3.5 Hardware/Software Requirements for IMAN PC

The following information was provided by Ricardo Schmidt on 30 Nov 1995:
IMAN PC:

ORECO format notes

The Coreco board in the IMAN PC has to be correctly formatted to work with the detector. The formatting information is contained in files with extension .vid. The iman program uses the file user.vid. That and other format files of historical or technical interest can be found in the directory: C:\odf64 on the IMAN PC.

The .vid file is created and modified by the program camera.exe. Execute it in the directory C:\ODX by typing simply "camera". This will bring up a semi-self evident control panel. It comes up displaying the parameters in the current user.vid file. At the bottom of the display it shows "fwin ncols nrows". The correct format currently is 688 cols and 570 rows. These are computed from the total numbers of rows and columns and the numbers of blanked rows and columns.
Specifically, the current values are obtained as follows:

number of rows: 574 total - 4 blanked = 570 rows
number of columns: 768 total - 5*16 blanked = 688

 

These values should be entered in the appropriate spaces in the control panel*.

 

The number of blanked columns is a multiple of 16.

The Open command (type Capital O) looks for .vid files and displays them in a rolling list from where they can be selected and examined.

The data are modified using the lower part of the control screen, the display updates to show the effect of the changes. The results may be Saved (type Capital S) and you are prompted to name the file to which the parameters will be saved. Normally you before running the camera program, you should copy user.vid to some backup file. Then the new file created can be called user.vid and will be ready for use by the iman program.

 

* Brooke hopes this is sort of semi-right --- he has never actually done this.

4.0 IMAN REDUCTION SYSTEM

4.1 Major Programs

The IMAN reduction programs are adaptations of the programs used at the NTT. They run on the machine which we designate the IMAN SUN; currently ctiot2. There are 3 Fortran programs:
IMANCAL processes a calibration image.

/ut22/iman/imancal file focus ut-date ut-time

where:

writes ascii output to:

iman.cal
* via German's routine spout
iman.log
iman.log.star
IMANSTAR processes a star image.

 

/ut22/iman/imanstar file focus ut-date ut-time gdr-x gdr-y gdr-rot

where:

writes ascii output to:

* via German's routine "spout"
iman.log
iman.log.star

IMANAV produces average results for the images previously processed with imanstar.

/ut22/iman/imanav

(no arguments)
writes ascii output to:

* via German's routine "spout"
iman.log

All arguments are strings. The file argument is the only one that is really needed. Output to * normally gets redirected to the Sun screen in front of the night assistant.
Imanav and imanstar communicate through the file /ut22/iman/iman.sums

Three cshell scripts are also used. The script rmi initializes the sums used in the averages, rmc erases old calibration data, and rmd deletes old star data images.

rmd

rm /ut22/iman/imans*.bin

rmi

rm /ut22/iman/iman.sums

 

4.2 Basic Subroutines

Imanstar and imancal call four subroutines which started life at ESO as four independent programs. These are:

• CGRV.
  This is the spotfinder routine. It first checks that the image contains enough pixels exposed above the background level, but not too many which are saturated. Then CGRV sweeps across the chip and finds the centroids of all bright spots, anywhere on the CCD, above a threshold which represents the local background. The output is a list of x,y coordinates of the individual spots, which is passed on to the next subroutine through a common block.
   
• NUMH.
  Receives a list of spots, in jumbled order and sometimes including spurious points. NUMH sorts the spots into the proper order; it identifies the individual spots with points in an ordered grid. To do this it first calculates the max, min and average of the measured x and y positions of the individual spots, to find the size and center of the overall spot pattern. It then goes to a point that is some pre-specified fraction of the way in from the edge of that pattern (chosen to be safely within the illuminated area of the donut-shaped pattern expected from a star), and tries to find a cross-shaped pattern of 4 points which are nearly equidistant from a central point, and at nearly right angles to each other relative to the central point. From that, it works out the spacing and angle of the grid pattern, and then proceeds to identify all of the other spots and assign them the correct indices within a two-dimensional array. The program has three chances to succesfully find a cross (it looks in up to three places), before it gives up and prints an error message.
   
• COMB.
  Aligns the spot pattern for the star with the corresponding spot pattern from the calibration image. The analysis is based on fitting to the shifts of the positions of the individual spots in these two patterns, but to calculate the shift it is necessary to know which spot in the reference pattern corresponds to a particular spot in the pattern from the star. The approach is to blacken out one particular spot (the lenslet is painted over), and then to automatically find this fiducial point in both the reference and star patterns. There are actually 4 widely seperated lenslets that have been painted out, to make sure that at least one of them will be illuminated by the star no matter where it is positioned in the field.
   
• SHAN.
  This is the Shack-Hartmann analysis program. It fits the seven terms: defocus, decenter, coma, spherical, astigmatism, triangular and quadrapole. Spots near the inner and outer edges of the pupil pattern are excluded.

4.3 Tweak Recommendation

The program IMANAV generates a recommendation about which aberrations should be corrected ("tweaked") and which shouldn't. This recommendation is presented as a "Y" (yes) or "N" (no) decision. The algorithim used is that the measured aberration must be above some minimum threshold, plus the average of the three individual measurements must be above some preset number of standard deviations of the individual measurements. The minimum threshold incorporates our experience with the measurement errors along with the criterion that any correction should be predicted to have at least some minimum effect on the predicted 80% encircled energy diameter of the image.

The present (3 Nov '95) settings for the Y/N criteria are:

Scale factor to convert from wavefront error to d80:

For most aberrations the minumum d80 is set at 0.1 arcsec. This is on the argument that if all five correctable aberrations have errors this size, they will combine in quadrature with a 0.5 arcsec image to produce 10% degradation in the observed d80. However, the spherical aberration measurements show such a huge scatter that the d80 threshold is set to 1.0 arcsec, effectively turning off this correction.

4.4 Sample Output

The output is sent to the TCS screen and also to a log file on the IMAN SUN called /ut22/iman/iman.log
8/17/00 UPDATE: the coreco board has exhibited problems for more than a year in the sense than about 50% of the time it doesn't update its buffer and doesn't transfer the last acquired image to the pc. Instead it keeps the last image and repeats it. That causes some errors in the averaging of the images for aberration calculations and induce the M1 tweak or M2 tilt correction to be unaccurate. The imanstar and imanav fortran programs were modified to include a comparaison test that does recognize any consecutive repeated frames and diregard them in the average calculation.

The results from a typical measurement will look like:

 

 

The output first shows results for the three independent 30 sec measurements. Magnitudes of the aberrations are given in microns (um), and the position angles in degrees (d). The rightmost column shows the residual 80% encircled-energy diameter that the image would have after correcting for all of the fitted aberrations (this residual includes the effects of slowly changing dome seeing components, but most of the effects of atmospheric seeing have been averaged out).

The next line gives the vector average for each aberration. After that is a line giving the standard deviation (1 sigma) of the magnitude of each aberration, and then a line giving the 80% encircled image diameter (in arcsec) which would be expected from each average value.

The line labelled "Tweak?" gives a recommendation about whether or not a correction should be made for each aberration: yes (Y) ==> make a correction; no (N) ==> do not change anything. A tweak adjustment is generally recommended for aberrations producing d80 values in excess of 0.1 arcsec, unless there is large scatter in the individual measurements. However, the spherical aberration measurements tend to show huge scatter, and we currently do not recommend making a tweak adjustment for that under any circumstances.

Finally, additional information about each measurement is grouped at the bottom left of the output. The first index increments with each frames analyzed, the second index (new at 8/17/00) shows the corresponding image number (i.e. 1,2 or 3) within a sequence allowing you to see which images were repeated/corrupted, "npts" is the number of spots used in the fit; "defoc" is the fitted defocus term (in microns); "decen" gives the fitted decentering term (in microns and degrees). The entries under "d80" are 80% encircled energy diameters at three different levels of correction: "init" is for no corrections; "coma" is with coma removed; "full" is with all fitted aberrations removed.

4.5 Log Files

The iman reduction programs write output onto a number of different log files:

• iman.log -- a log of all of the output that has gone to the TCS screen. Each entry will look like the example given above (Section 4.4). This is a intended to be a running log going all the way back to the dawn of time.
• iman.log.cal -- gives a more verbose level of information about the calibration reduction. It is overwritten each time imancal is used.
• iman.log.star -- gives a more verbose level of information about the star reduction. It is overwritten each time a new star sequence is started, so it typically contains information about the reduction of the previous set of three images.
• iman.log.av -- gives one line of summary information for each star sequence: UT time, UT date, hour angle, declination, rotator angle, number of reductions averaged together, number of used reductions in a sequence of 3 (this parameter is new at 8/17/00, because of the coreco problem that repeats frames and therefore results leading to corrupted average), defocus, decenter, decenter pa, coma, coma pa, spherical, astig, astig pa, trefoil, trefoil pa, quadrafoil, quad pa.

This is intended for creating the input for the auxilary programs "listav" and "listmap" (see Section 4.6, below), and would typically be deleted at the start of an engineering night when the sky is being mapped with IMAN, etc.

Example of iman.log.av: a 'star sequence' (3 images ok) followed by a 'more star' (2 images ok) averaging 5 different frames to calculate the aberrations

References to individual entries in iman.log and iman.log.av are by the time stamp; so be sure to record the UT time and date in any handwritten logs you may also be keeping.

When imancal, imanstar and imanav are run from the TCS, they write into the versions of these log files which are in the directory /ut22/iman. When the auxilary programs such as testseq are run, they write into versions of these log files which are in the current directory.

4.6 Auxiliary Programs

The statements for opening files which are normally used by imancal, imanstar and imanav have the full path name to /ut22/iman hardwired into them, and will crash unless run through German's calling procedure from the TCS. Each of these programs has a separate test mode which lets them access files in whatever directory they are run from. The test mode is activated by entering the word "test" as the third argument for imancal or imanstar, or as the first argument for imanav.
To make this mode easy to use, there are three c-shell scripts called testcal, teststar and testav, which directly call imancal, imanstar and imanav, respectively. They should be called as follows:

testcal [image] [f/ratio] [name]

teststar [image] [f/ratio] [name]

testav (no arguments)

 

The argument [image] is the name of the disk file containing the binary ccd image. [focus] should be either "f/8" or "f/14"; f/8 is assumed if no value is given. [name] can be any one-word name; it will be written into the header part of the output record.

To make it easier to save and re-analyse data, three additional c-shell scripts are provided:

There are also four auxilary programs which process the output contained in the file iman.log.av. That file contains one line of information for each of the three-exposure sequences, listing the time, telescope position and average values of the aberrations. The programs for further processing are:

The input file "list.in" must be in the same format as the file "iman.log.av". The intention is for you to copy iman.log.av into "list.in", and then to edit out any parts that you do not want to include in a specific reduction run.

All of these auxiliary scripts and program executables are found in the directory /ut22/iman. Modified versions of 'listav' and 'listmap' that will work with the new -as of 8/17/00- format of iman.log.av are to be found at /ua76/boccas/4m/iman/. To set aliases for them in your current directory, type "source /www/4m/iman-alias".

4.7 Testing Iman

The best first-order check of whether or not the full IMAN system is working is to take a CALIBRATION SEQUENCE, followed by a STAR SEQUENCE with the aperture wheel in the CALIBRATION POSITION. The calibration sequence should execute all of the way through and finish by telling you that a new calibration has been stored on disk. The star sequence should produce a saturated comparison spot pattern on the IMAN display, and should execute all the way through and return small aberrations as its result (~0.1 nm in magnitude).

Further subtle errors can occur which are most easily spotted by a closer examination of the IMAN images. Samples of good images can be found in /ut22/iman/samples. Some techniques for using IRAF to look at IMAN images in detail are described in /ut22/iman/samples/README.

4.8 Error Messages (and what to do about them)

ERROR -- STAR IS TOO BRIGHT. From CGRV. Too few spots have been found and more than 1000 pixels (average of about 5 per spot) have signal levels of 4095 (CCD saturation). Find a fainter star.

ERROR -- STAR TOO FAINT. From CGRV. Too few spots have been found and less than 500 pixels are more than 150 ADU above the background. Find a brighter star.

ERROR -- BACKGROUND TOO BRIGHT? From CGRV. Too few spots have been found and the average ADU/pixel is more than half the saturation value. Find a darker sky.

ERROR -- FOUND TOO FEW SPOTS. From CGRV. Too few spots have been found and none of the 3 previous errors have been detected. Take another star sequence and watch the IMAN image display monitor as the 30 second exposures are read out. Is the star way off center? Does the image turn to noise half-way through the picture?

ERROR -- CANNOT FIND SPOTS ABOVE THRESHOLD. From CGRV. Signal too weak or background is too bright. Find a brighter star.

ERROR--CANNOT REDUCE MORE THAN 99 IMAN IMAGES. The arrays in IMANSTAR are dimensioned to hold data for only 99 images when the MORE STARS command is used. Control yourself.

ERROR--COULD NOT ALIGN OBJECT AND CAL GRIDS. From COMB. Unable to identify a dark spot in the star pattern with one in the calibration pattern. Try moving the star in the aperture until the donut image includes a dark spot with a bright spot on each of it's four sides.

ERROR -- COULD NOT FIND ALL 3 DARK SPOTS IN CALIBRATION IMAGE. From COMB. When processing a calibration image (but not a star image) the system requires that all three dark spots be detected. (A detail... there are actually four Shack-Hartmann lenslets that are blacked out, but the program only knows about three of them). Recovery... try taking another calibration frame. If that fails, just use the old calibration, which should still be available for use.

ERROR -- COULD NOT OPEN CALIBRATION FILE. From IMANSTAR. The file /ut22/iman/iman.cal does not exist. Take a new calibration.

ERROR -- COULD NOT READ iman.sums FILE. From IMANSTAR. Error encountered while reading iman.sums. Start the star sequence again.

ERROR -- COULD NOT READ STAR DATA FILE. From IMANSTAR. The Sun did not receive the data image from the IMAN PC. Follow the IMAN PC restart procedure.

ERROR -- DATA FILE NOT FOUND ON SUN. From CGRV. The image file which was supposed to be sent from the IMAN PC could not be opened. Follow the IMAN PC restart procedure.

ERROR -- GRID COULD NOT BE IDENTIFIED. From NUMH. It was not possible to organize the spots into a square grid pattern. Sometimes caused by cosmic ray hits adding spurious spots. Try taking another star sequence.

ERROR. IMAN calibration not saved. From IMANCAL. General warning that a new calibration was not produced. The previous calibration should still be on disk ready to use.

ERROR -- NO CALIBRATION IMAGE ON SUN DISK. From IMANCAL. The Sun did not receive the calibration image from the IMAN PC. Follow the IMAN PC restart procedure.

ERROR -- NOT ENOUGH POINTS IN GRID. From NUMH. Grid was identified, but it contained fewer than 150 spots. Try recentering star in aperture.

ERROR -- SIGNAL TOO WEAK. From CGRV. Fewer than 500 pixels have signal level above 150 counts (as compared to typical background level of ~100 counts). Find a brighter star.

5.0 IMAN CONTROL SYSTEM

5.1 Menu Commands

IMAGE ANALYZER

The IMAN control system is the section of code within the TCS software which accepts the above commands from the telescope operator and then translates them into other commands which are issued to the IMAN optics, camera and reduction systems in the correct sequence. The interactions between the different elements of the IMAN system are sketched in figure 4.

Some of the above commands cause only one operation, but others are converted into long sequences of commands to different devices. Typical sequences are given below. Commands starting with "iman" are sent to the iman optics, those starting with "iman pc" are sent to the IMAN PC, and those starting with "tcp" are sent to the TCP program which then sends them on to the IMAN SUN.

The TCP commands are followed by an integer 1-5 which selects follow-on actions after completion of the SUN task which appears as their arguement. In particular "tcp 4" starts the reduction of image imans3.bin (as specified in the argument), waits for completion of the imanstar task, then initiates the imanav task on the SUN.

 

5.2 CAL SEQUENCE command:

iman pc s
iman pc status (WAIT IN LOOP UNTIL "IDLE" IS RETURNED)
iman pc cal
iman pc status (WAIT IN LOOP UNTIL "GRAB" IS RETURNED)
tcp 5 /ut22/iman/imancal cal001.bin

5.3 STAR SEQUENCE command:

5.4 MORE STARS command:

Same as STAR SEQUENCE command, except that the following command is not sent:
tcp 1 /ut22/iman/rmi
Not sending this command has the effect of not clearing the sums and counters used to compute the averages and standard deviations of the aberrations. Thus, additional sets of three stars can be incorporated into the running averages. A maximum of 33 sets of 3 star observations each (99 observations total) can be averaged together.

5.5 OBSERVE POSITION command:

iman pc s
iman flat in
iman camera off
iman aperture small