Personal tools
You are here: Home / COSMOS2 / align-mask


Back to Programs


align-mask uses a direct, or dispersed, image of a slitmask to improve on the (1) scale (2) rotation and (3) x,y offsets values given in an existing dewar offset file. Output is a new dewar offset file. align-mask predicts the locations of apertures (or spectral lines) in an image of a mask, using the observset observation definition file. It searches near each predicted location for the expected apertures/lines and calculates offsets for each. From the set of offsets, the program solves for the focal plane scale, rotation angle, and x,y offsets which will minimize the median errors. Although align-mask can be used with any image, it is advisable to use either a direct image with well- spaced apertures, or a dispersed image with well-isolated lines, particularly if the expected position errors are significant (greater than a few pixels).
HINT: If you wish to iterate on a fit, remember to change the name of the dewar offset file to framename in the observation definition file after the first iteration.

USAGEalign-mask -o observset -f framename
INPUTframename is a set of image files containing a direct or dispersed image of a slitmask observset.obsdef is the name of an existing observation definition file which describes the observing setup used for the frame and specifies an existing dewar offset file
OUTPUTframename.dewoff, a new dewar offset file.
searchboxhalf-width of search range (in pixels)
magfactormagnification factor (in plot) of offset vectors
lamfilefile with list of comparison lines to use with dispersed image
navernumber of neighboring vectors to average in plot (normally =1)
thresholdminimum strength of apertures/lines used, as multiple of background
siglimitline rejection threshold
maxfluxmaximum flux


When first invoked, align-mask calculates the predicted positions of all the apertures (or lines), then searches near these positions for the apertures/ lines. Only apertures/lines stronger that threshold x background are included (a useful value of threshold is a few tenths, if your frame has not had bias subtracted). If you are using a dispersed (rather than direct) image, align- mask searches for the images of each spectral line listed in lamfile. If you expect the initial alignment to be pretty good, start with parameters searchbox = 10 and magfactor = 100. A plot of the position errors for all apertures found is first presented:

align-dewar gui
68 matches found. sigma =   1.95 pixels. Continue?

You should see most of your apertures. If you see very few, chances are that something is very wrong with the dewar offset file. If you get just points near the middle, with vectors indicating rotation, your rotation angle is probably off; proceed as described below to adjust. If there are a few widely scattered or no points, your x,y offsets may be so far off that the program cannot find the apertures. Try increasing searchbox to 20, then to 50. If you still can't find your apertures, you probably either have the wrong mask/SMF file combination, or the mask is rotated by 90 or 180 degrees or the dewar rotation is set wrong (Normal vs Nod&Shuffle;). If you can't figure it out, try running apertures (for a direct image) or spectral-lines (for a dispersed image) and comparing the mask image with expected spot locations. If there are lots of very long vectors, you may want to quit [answer "n"] and rerun the program with a smaller magfactor.

If things don't look hopeless, answer "y" and the following dialog will occur:

Average scale =      0.99997   Reset scale?

Normally, the scale only varies by a few parts in 10**4. If scale differs from 1.000 by that much, you may want to say "y". If less, don't bother. If much more, something else is very wrong with the fit. Answer "n" on this iteration and proceed. Next:

Average rotation angle = -0.001   Reset angle?

It should be apparent from the plot if significant rotation is present. Unless the number seems wildly inconsistent with what your eyes tell you, answer "y". Don't bother if the angle is less than a few thousandths of a degree.

Average X,Y Offsets =   0.2   -0.1 pixels  Apply shifts?

Normally, answer "y" unless the offsets are 0.1 pixel or less.

Now, set the name of the dewar offset file in the obsdef file to that produced by this iteration of align-mask, and run the program again. If you had increased searchbox significantly above 20, or decreased magfactor much below 100, you may want to change them again. Your final sigma should at most be a few pixels unless there is a problem with the mask or setup.


  • There is a limit to the number of slit images that can be handled. If you are using a dispersed image with very many slits, pick a small number of isolated comparison lines.
  • The parameter naver should normally be set to 1, except for unusual cases of very noisy data.

Back to Programs