Autofocus Script (LMI) for LOIS

Overview

How

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.

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 (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, 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 between 750-900 microns. 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, 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.

Aborting a Focus Run

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.

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

TESTFOCUS LOG

A sample log entry:
+++++
Focus in place () .5 (1, 1) results run
2013/05/29 05:09:43
Current tube temperature is 0.0
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 0.0
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 0.0
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.

• Third line- The nominal "tube temperature" (or whatever interesting temperatures or temperature might apply to the activity) would go 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: The focus value from the Fifteenth line is the one set automatically by the script.
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 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.

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.

• 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).

• 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.

LMI Definitions Applicable To The Focus Script

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