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 with the green UI button in the usual way. There should be an inplacefocus button under the User Buttons tab on the LMI UI to run the script. 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. There is also a setfocus script and User Button available to unconditionally set the focus value.

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.

inplacefocus x y title bin exptime filter focstep focbase flags

The user first selects a star with coordinates x,y in pixels on a full frame left amplifier single image, usually binned 2:2. The script then takes subframe images centered about these coordinates, with a succession of focus settings, to find the best image quality.

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 (200x200 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, 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 without a result.

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 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 without a result. This could happen, for example, if clouds covered the star in midsweep. The focus script can also adjust the exposure time 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 between 750-900 microns. Note that there is no internal focusing element in the LMI instrument.

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 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 is not supported; such exposures can be taken, but are subject to image contamination due to lack of an optically masked transfer area.

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 rage
• 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, or is still at the top or bottom of the sweep after a second sweep, 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 directory 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. 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.

The focus run can be aborted in the usual way 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.

TESTFOCUS LOG

TBW

A sample log entry:
Note: The entries for focus steps 950 and 1000 have saturated maximum pixel values (65535). This degrades the quality of the fwhm, and thus focus, measured.

+++++
Current tube temperature is 0.0
800 107,106:26706.00, Cent=107.29:106.18 Fwhm=7.63 Mag=8.54 Sky=6154.02 fom= 0.6960, 0.0 0,0
850 105,107:53267.00, Cent=105.50:107.05 Fwhm=6.71 Mag=7.89 Sky=2722.31 fom= 0.7629, 0.0 0,0
900 106,107:51107.00, Cent=106.55:107.25 Fwhm=7.10 Mag=7.89 Sky=2900.38 fom= 0.7319, 0.0 0,0
950 107,107:65535.00, Cent=107.71:107.63 Fwhm=6.06 Mag=7.84 Sky=3658.44 fom= 0.8963, 0.0 0,0
1000 109,107:65535.00, Cent=109.20:107.28 Fwhm=6.12 Mag=7.69 Sky=3329.07 fom= 0.7807, 0.0 0,0
1050 109,108:64520.00, Cent=108.87:108.06 Fwhm=6.42 Mag=7.76 Sky=3366.52 fom= 0.8198, 0.0 0,0
1100 109,107:56617.00, Cent=108.94:107.48 Fwhm=6.74 Mag=7.85 Sky=2805.64 fom= 0.7815, 0.0 0,0
1150 111,109:36011.00, Cent=110.59:108.80 Fwhm=8.08 Mag=8.09 Sky=4776.80 fom= 0.6201, 0.0 0,0
1200 108,106:25680.00, Cent=108.85:106.57 Fwhm=8.14 Mag=8.97 Sky=7243.37 fom= 0.9945, 0.0 0,0
2013/03/27 04:18:45
Best focus at 950 fwhm = 6.06 tube temp 0.0
Parabolic fit to fwhm data: X= focpos - (1000)
Parabolic Fit constants 4.3207792207792206e-5X**2 + 0.00193X + 6.27987012987013
best focus 977.6660655244965 from parabolic fit
Best focus at 1200 fom = 0.99448 tube temp 0.0
Parabolic fit to fom data: X= focpos - (1000)
Parabolic Fit constants 5.138961038961946e-8X**2 + 0.00026268333333333315X + 0.786220173160173
best focus out of range from parabolic fit

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 850 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 (q.v.).

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.

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.

• The script probably does not work for camera binning factors other than 2:2.

• It would be useful to put some temperatures data in the focus log.

• 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 (because LMI LOIS can't).