Autofocus Script (LMI) for LOIS

Overview

The focus script is a Tcl script that runs under LOIS. In the case of LMI, it is available after LOIS has been started and initialized in the usual way. There may be an inplacefocus button under the User Buttons tab on the LMI UI to run the script but the preferred way to run the focus is through the imager. It is necessary for the TCS and AOS to be running and the usual connections via JOE established to perform the focus changes that this script will make.

The focus value is technically called the focus offset with units of microns – it is a direct piston of M2 applied in addition to the continuous update for temperature and elevation angle provided by the AOS. Changing the focus for LMI will also change the focus for the probe cameras and other instruments in the instrument cube.

The operation consists of 4 general steps:

1. Taking a test image
2. Setting up focus parameters & initiating the focus sweep
3. The focus sweep
4. Display of the focus sweep results

For reference, the command sent to LOIS is in the following form:

inplacefocus x y title bin exptime filter focstep focbase flags

So the user first takes a full frame left amplifier single image, usually binned 2x2. The user then sets up the focus parameters and initiates the focus sweep by selecting a star from the initial full frame image. The script then takes subframe images centered about the star, with a succession of focus settings, to find the best image quality. And finally a dialog box comes up displaying the results and the associated parabolic fit where the user can decide on the appropriate focus offset sent to the AOS.

Operation through the Imager

The focus script/operation can be initiated through the imager. The first step is to take a full frame left amplifier single image, usually binned 2x2. A star on this image will be used as the basis for the focus sweep. 

The "Focus" drop-down menu in the imager has 2 items; one for setting the parameters and the other one for initiating the command:

Selecting "Focus Parameters" brings up a dialog box with pre-filled values:

Two of these parameters deserve some explanation. The bin value is not editable and is pre-filled based on the setting chosen in the previous full frame image. In the case of the LMI, the Focus Base is adjusted from the value in the config file by the differential focus offset value for the current filter. So if the value in the config file is 1540 µm and the current filter is V, the default value would be 1710 µm.

The first time the "Focus Run Parameters" dialog box comes up, the values will be the default values which are read from the config file. Most of the times, the default values are a very good place to start. But if for some reason, the user decides to change some of these values, they will be saved and used the next time the dialog box comes up. If a pre-filled value in the text box is not the same as the default, the color will change to red and the suggested default value will display in front of the text box. In the example above, the focus base is set to 1540 which would be the saved value from the previous run and we see that the suggested default is 20.

Selecting "OK" saves the parameters and we will be ready to initiate the focus sweep. "Reset to Defaults" and "Clear All Values" are self explanatory but the "Redo Focus Run" should be used with care. This button is used to repeat a focus run (same star and therefore same x & y coordinates) with different parameters. The button saves time by not repeating the initial step of taking a full frame image.

The second item on the drop-down, "Mark & Initiate Focus Run", allows selection of a target star by clicking on it. The x & y coordinate of the star is included in the inplacefocus command sent to LOIS. If a user selects this action, the imager will be expecting a mouse click event indicating the star to be used for focus sweep. This action can only be aborted using the ESC button. Otherwise the next mouse click inside the imager will initiate a focus sweep.

For the details of the operation of the inplacefocus script, please refer to the sections below. After the focus sweep has completed, the script sends a message to the imager containing the focus steps and the associated FWHM values:

02:52:10 Level_9:FOCUS_PARAMS=800.0,18.58|830.0,16.85|860.0,20.44|890.0,15.47|920.0,16.34|950.0,17.75|980.0,20.83|1010.0,21.41|1040.0,22.30

Upon reception of this message, the imager will generate a modal dialog box with three tabs. The first tab is the focus plot with the parabolic fit, the second one is the residual plot, and the third tab is the tabular data:

The fitted focus position is pre-filled in the editable text box at the bottom panel. Clicking "OK" will send this value to the AOS. Of course the observer has the option to change this value and send some thing else to the AOS. Clicking the "Cancel" button will send the focus base to the AOS.

The first tab has some annotations and if p-value < 0.9, the font color becomes red. This is an indication that the fit is most likely unreliable. The third tab has a table of the data used in the plot & one can copy the data by highlighting and using either ctrl-c or command-c. This is probably unnecessary for the experts because the IDL stuff and the related files are still accessible if a user feels more comfortable with those.

Method

There is no slew to locate the star, or telescope motion to center it up, whence comes the term "inplace focus". The focus setting value used as the center of the sweep is called focbase; the script first sets the focus to that value. The routine then "acquires" the star by defining a standard sized (now 300x300 at 2:2 on LMI) subframe around the given position and taking a single image. Analysis is performed on this image- if the star is sufficiently bright, in terms of instrumental mag. and maximum pixel value, but not saturated, and the fwhm is reasonable, the subframe is redrawn to place the psf in the center of the image. If the image appears reasonable, but either too bright or faint, the exposure time will be adjusted within certain limits and the exposure retried. If this is still out of specification, the focus script ends with a failure status.

When the acquisition is complete, the routine initiates a "focus sweep" in which the focus setting is moved in steps from a value considerably lower than the focbase to one considerably higher. At each setting a "focus image" is taken , and another analysis is performed. If the brightness and fwhm meet similar kinds of criteria as those for acquisition, the focus is moved to the next step. Otherwise the image is retried; when retries are exhausted, the script usually terminates with a failure status. This could happen, for example, if clouds covered the star in midsweep. The focus script can also adjust the exposure time up or down after a measure taken during the focus sweep, prior to a retry, but within narrower limits than those used at acquisition. On LMI, there is one retry available during acquisition, and also one per individual measure within the sweep.

When the focus sweep is finished, the focus value with the smallest fwhm is selected to be the new focus setting. If the focus setting is at the top or bottom of the sweep, the focus sweep is repeated with the center of the second sweep defined to be the best focus step found in the first.

The focus value is ordinarily defined to be the position of a focusing element. On LMI, the definition is somewhat abstract: it is the offset in microns from the nominal focus selection of the AOS for M2 as mentioned above. This is typically around 1540 microns with no filter in place, the open position. Note that there is no internal focusing element in the LMI instrument.

Some Options

The focus script can be performed in any filter; however, at present this filter must be selected with the filter wheel icon on the UI prior to running the script. The focus value obtained by the script will be used as-is whenever the observer is in that filter. If another filter is selected, the tabulated focus-filter offset for that filter will be applied to the existing focus value, by JOE.

The focbase mentioned above, along with the focstep, the size of the focus step, are arguments to inplacefocus, with reasonable defaults. The number of focus measures is usually 9, including the central value, but that can be redefined if necessary with the focstep argument as well.

The method for taking images for measurement at each focus step is also selectable. You may take a single, or n multiple singles, or on some instruments, a subframe basic occultation with n frames (ie NAXIS3=n). In either case, if multiple frames or singles are used, the fwhm or other figure of merit for that step is an average of the analysis values obtained for the group. On LMI the basic occultation option is not supported with the focus script; such exposures can be taken, but are subject to image contamination due to lack of an optically masked transfer area.

Focus and Other Outputs

There are several focus estimates made at the end of a focus sweep. These are based on

• minimum fwhm
• maximum ratio of peak pxl to flux (figure of merit, or fom)
• minimum of parabolic fit to fwhm values, if within the focus sweep range
• maximum of parabolic fit to fom values, if within the focus sweep range

The estimates are printed in the lois log and in the focus log. the final focus setting adopted, however, is that based on the minimum fwhm criterion. You are not obligated to accept this focus. The setfocus command and user button can be used to select another focus. If the focus script fails, or is aborted, the focus setting is restored to focbase.

There is a focus log to which the results of each focus run are appended; on LMI this is called testlmifocus.log and lives in the obslemi home directory on computer lemi.

The images taken with this routine are test.fits images. The "save" flags setting will make a subdirectory for this focus run, in the main image data path for the rundate, to save named images for each focus step position. The name of the subdirectory matches the hh:mm:ss timestamp used for the focus run in the focus log.

The script normally stops if an acceptable star image is not available, either during acquisition or at any focus step, following retries. The conditioning flags setting causes all focus sweeps to run unconditionally to the end; however the focus setting is restored to focbase at the end regardless of results- this mode of operation merely updates the focus log, which also allows a focus plot to be made. 

A Few Error Messages You Might Get (Lois Log, Level_11)

• Unknown flag xxxx  (bad flags argument)
• x: not a number (also for bad exptime, bin, focbase, focstep and y arguments)
• Focus script sees invalid inputs, returning ..   (result of bad numbers)
  
• Selected  x  (Y)  coordinate is off array or too near edge (could be a result of confusion about binning)
• Exposure time is out of range  (see longexp flag)
• Star very faint. near bias level, not adjusting etime (what you get for instance on a box with only background)
• Star too bright, could not adjust etime given adjustment limits (these limits are currently about a factor of 2- similar message if star is too faint)
•  Star too bright, maxpxl saturated (actual saturation, etime will not be recomputed- several variants on this message)
  
• Saturation of subframe (this is caused by bright background or a very bright star on the same row- related to ccd firmware bug)
  
• Try again, clouds may be involved (if a star that had been in brightness range is now out of range, unexpectedly)
•  Focus Script Stopped by User  (You hit the Stop Series button to abort the focus)

•  This parabolic fit focus is below the bottom of the range and rejected  (or above top of range- not a failure, but the focus was off center and a fit solution would be unreliable)
  

Aborting a Focus Run

A focus run may be aborted with Stop Series  button.

1. Open LMI Control view.
2. Push the Stop Series button on the top row.
3. wait some seconds, and the LOIS log should indicate the script is aborting.
4. The script will set the focus back to the value of focbase.

The focus run can also be aborted as it has in the past, with ./abscript:

1. Go to the home directory for obslemi in the console where you started LOIS.
2. type ./abscript
3. wait some seconds, and the LOIS log should indicate the script is aborting.
4. The script will set the focus back to the value of focbase.
5. now type ./abscript clear; if you fail to do this the focus and other scripts will abort immediately on startup.

Note: You cannot abort the focus script with abquick, because the script responds too slowly.

Parameters

The defaults for the focus script, and other relevant parameters for the operation such as the size of the aperture masks for photometry, are defined in the definitions file for LMI. (dct_lmi_defs.tcl).

TESTFOCUS LOG

A sample log entry:
+++++
Focus in place () .5 (1, 1) results run
2013/05/29 05:09:43 TYC 0326-00936-1 20 1 12 0 -12 12
Current tube temperature is 10.18
Focus run in nominal band internal Focus binned 2:2 1 per step
Test subframe 6: 1558:1500, 300 x 300
570 104,101:7445.00, Cent=101.76:100.90 Fwhm=12.33 Mag=8.48 Sky=1177.67 fom= 0.1836, 1.56 0,0
620 101,102:9742.00, Cent=100.75:101.74 Fwhm=10.86 Mag=8.32 Sky=1159.13 fom= 0.2073, 1.56 0,0
670 102,102:9511.00, Cent=101.24:101.99 Fwhm=11.00 Mag=8.40 Sky=1188.90 fom= 0.2179, 1.56 0,0
720 101,102:16209.00, Cent=100.62:101.97 Fwhm=8.59 Mag=8.29 Sky=1130.09 fom= 0.3356, 1.56 0,0
770 101,102:18143.00, Cent=100.47:102.00 Fwhm=8.29 Mag=8.27 Sky=1130.08 fom= 0.3687, 1.56 0,0
820 101,102:15771.00, Cent=100.48:102.24 Fwhm=8.83 Mag=8.28 Sky=1137.33 fom= 0.3235, 1.56 0,0
870 101,101:13418.00, Cent=100.92:100.60 Fwhm=9.46 Mag=8.32 Sky=1146.34 fom= 0.2856, 1.56 0,0
920 99,102:10967.00, Cent=99.03:101.68 Fwhm=10.01 Mag=8.40 Sky=1140.93 fom= 0.2512, 1.56 0,0
970 101,104:7307.00, Cent=100.82:103.22 Fwhm=12.13 Mag=8.52 Sky=1230.03 fom= 0.1870, 1.56 0,0
2013/05/29 05:12:42
Best focus at 770 fwhm = 8.29 tube temp 10.18
Parabolic fit to fwhm data: X= focpos - (770)
Parabolic Fit constants 8.88961038961039e-5X**2 + -0.0020633333333333333X + 8.685064935064936
best focus 781.6053080107134 from parabolic fit
Best focus at 770 fom = 0.36873 tube temp 10.18
Parabolic fit to fom data: X= focpos - (770)
Parabolic Fit constants -3.904813852813855e-6X**2 + 8.949333333333323e-5X + 0.3273380086580087
best focus 781.4593597424424 from parabolic fit

What this means

• First line- it is a focus in place, with a nominal exposure time of .5 seconds. There is 1 sample or measure per focus step, and this is a single- it is a "results" as opposed to a conditioning run, which means the focus determination will be applied.

• Second line- time and date of the start of the focus sweep- also the name of the "save" subdirectory, if any, would be 05:09:43. As of 2013 June 22, the Science Target name and position are appended to this line.

• Third line- The nominal "tube temperature" (or whatever interesting temperatures or temperature might apply to the activity) would go here. As of 2013 June 22, the AOS MNTTEMP is provided here.

• Fourth line - filter is "nominal" (later on actual filter names should appear), the binning of the subframes is 2:2 with 1 sample per set.

• Fifth line- the (internal) subframe position and size after acquisition- it is slightly larger than that used for acquisition.
• Next 9 lines- the individual focus measures, giving focus value, max pixel x, y and signal in ADUS, centroid x, y, FWHM, instrumental mag., sky background, figure of merit, and actual exposure time. In this case the nominal exptime was increased by a factor of 3.
• Fourteenth line- the time stamp representing the end of the focus sweep.
• Fifteenth line- The best focus based on minimum fwhm with the corresponding fwhm value and the tube temp.
• Next 3 lines- the coefficients of the parabolic fit to fwhm vs focus and the minimum fwhm according to that fit.
• Eighteenth line- The best focus based on maximum fom with the corresponding fom value and the tube temp.
• Next 3 lines- the coefficients of the parabolic fit to fom vs focus and the maximum fom according to that fit.

Note: In a results run, the focus offset was set automatically from value in the Fifteenth line.

Note: The fom or figure of merit is defined as the ratio of the peak pixel in ADUS to the total aperture photometry flux- here, the flux is based on the given instrumental magnitude and a zero point that has a flux of 1.0 ADU/sec at instrumental magnitude of 20.0. The more sharply focused the star, the larger the fom. The use of fom generally assumes the inst. mag is constant across the focus sweep, which is not strictly true in some cases.

PROCEDURE

The TCL code to run inplacefocus is sourced automatically during startup and initialization of LOIS.

It can be resourced by

• using the SrcLMITools user button.

which is done during testing. Resourcing at any time should be harmless, but unnecessary for observers ordinarily.

You need to move to the desired filter with the UI filter wheel view first, since LOIS cannot move the LMI filter wheel at present. The filter argument for inplacefocus should likewise always be left blank.

You should preset the focus offset to 1540 microns (or any known happy focus value from experience) using the stdfocus button or asking the telescope operator. You will also use this for focbase.

A star is acquired and a full frame test single (binned 2:2 on LMI) taken with a 1 or 2 second exposure. The star should not be too far from the center, and be significantly brighter than anything in its vicinity. You'd like to get 10-20K ADUs for the peak pixel with this exposure ideally. The focus script will do some autoadjust of the exposure time if needed, but you want to avoid getting an exposure time shorter than a second or very long. A short exposure will not average the seeing very well.

Since the script must pass through the focus minimum to obtain a useful result, it's important to use a large enough step to catch the minimum and also large enough to give a clean focus 'signal'. On nights of average seeing 40-50 micron steps are good for LMI. The steps might be increased if the seeing is bad. The two obvious ways that a script of this kind can give you a bad focus setting are

• Using a focstep size too small for the seeing conditions.
• Running the sweep very far out of focus- this should not occur on LMI.

You want to see something like a parabola with decently distinguishable minimum when plotting fwhm against focus, as with focnext ( see http://sabzi.lowell.edu:8080/confluence/display/LIGS/Focus+Log+Plotting ).

In principle, a focus setting once made will be maintained through the night by the AOS automatic update, irrespective of elevation angle. If this were strictly true, only one focus run would be needed per night, and the best place to do that would be at an elevation of 60-70 degrees from the horizon, where the seeing is better. This is probably not true as yet, and the jury is out as to how often focus runs need to be done. This question interacts with the similar question of how often the AOS needs a WFS correction update.

ARGUMENTS LIST

inplace_focus x y title bin exptime filter focstep focbase flags

If the user button is used for this command, there should be neither quotes nor curly braces embedded in the fields for these arguments. The arguments are ordinarily single strings without embedded spaces, or empty strings (all spaces) in each button field. But, the exptime, focstep, title and flags fields can accept strings with multiple tokens, i.e., separate options separated by one or more spaces.

Exptime is a floating point value for exposure time in seconds, defaulted as 1.0. If specified as two tokens, the second value is the number of singles to be taken, defaulted as 1. If specified as three tokens, the second value is the number of basic occultations to be taken, and the third value is the number of frames (NAXIS3) for each occultation. Occultations not currently available for LMI.

If focstep specified as two tokens, the second value is the number of steps in the focus sweep, which defaults on LMI as 9.

In regard to flags, the name of the save subdirectory includes the timestamp, which is also used in the focus log and represents the start of the focus sweep proper; the file names used include the focus setting.
Script runs to completion with conditioning irrespective of image contents; it can be run without any star.

Examples

Do a simple focus run for a star located on an LMI test single binned 2:2 at pixel 1578, 1322. The run is being started at 05:13 UTC. A first guess of 900 microns offset will be adopted for the focus, with a coarse step size of 100 microns.

The title is put into the header for this run in the focus log testlmifocus.log. The binning is defaulted to 2:2, and the filter is defaulted to "nominal" which means the filter wheels will be left where they are.

Because of the save flag, there will be a subdirectory of the data directory called 05:13:12

with files

each of which is a subframe image for the corresponding focus step.

Bugs

• The script may still occasionally throw TCL errors (ugly multi-line error messages with UI popups). These should be reported with the time of occurrence.

• The script may still occasionally terminate without a clear indication that it has completed, or whether it succeeded or not.

• It would be extremely helpful if the LOIS analysis measured image ellipticity and this were logged and displayed during focus runs.

• The LMI version of focus can't adjust the filter (even though LMI LOIS can, now).

• The 'fom' ratio is peak/flux- it would be better to use peak/(flux*etime). This could only affect the focus outcome if the etime varied during the sweep, which is possible with the exposure time adjustment. In practice this rarely happens, because the adjustment is already done in acquisition.

• On LMI, the instrumental magnitude increases a bit at the wings of the focus sweep- almost certainly means the object apertures for photometry are too small.

• The acqtry parameter is not honored.

• Changing the focus takes too long, because it is being run open loop; defining when a focus offset move is complete turns out to be tricky.
  
  
• There is a bug in the CCD firmware that will cause anomalous saturation artifacts to appear on the left hand part of a subframe (given an A amplifier readout) either in a bright background situation (twilight or near the Moon) or if a star that is considerably brighter than the star being used for focus  is located to the left of the focus/acquisition subframe. If the pixels of the artifact intrude into the focus/acquisition analysis box, these will be picked up instead of the star and usually cause a focus failure. The size of the focus/acquisition subframe has recently been increased, without expanding the analysis box size, which has substantially mitigated the problem.  It's now possible to focus within a few degrees of the Full Moon.  

LMI Definitions Applicable To The Focus Script (THESE VALUES AREN'T CURRENT)

These are all in the LMI TCL definitions file. It is not recommended for observers to modify these.