FITSRegister User's Manual
Sky Coyote, 6 Oct 2006


  1. Preparing FITS images
  2. The settings window
  3. Loading file 1 image
  4. Loading file 2 image
  5. Showing image headers
  6. Swapping images
  7. Zooming images
  8. Getting mouse values
  9. Setting the circle
  10. Setting the lines
  11. Shifting file 2 image
  12. Saving image 2
  13. Equalizing scale settings
  14. Removing video noise
  15. Using keyboard commands
  16. Multiple image alignment procedure
  17. Alignment issues
  18. Setting default settings
  19. Saving/loading documents

Preparing FITS images

FITSRegister reads FITS files which contain a single 2d monochrome image. That is, each FITS file must contain an image (not table) in the first HDU, and that image must have 2 axes (NAXIS = 2). See the FITS website for more information about these parameters. The orientation of images displayed with FITSRegister is: X axis = right, Y axis = up. That is, the first pixel in the FITS file will be displayed at the lower left corner of the image window. There is a setting you can use to flip the Y axis of an image if you desire, so that the origin is then at the top left corner, and Y is down.

To download the 2 Venus images used in this tutorial, click here ( If you reuse these images in another publication, you should reference Eliot Young, Mark Bullock, and the NASA IRTF, 2004.

The settings window

Each FITSRegister document contains 2 windows, a settings window (the main window), and an image window (which displays the FITS files). The settings window contains the controls used to load images, set their display properties, shift and animate images, and show and move geometrical alignment aids. The settings window is a fixed size, but the image window can be resized and scrolled. You can create as many FITSRegister documents as you like by choosing the 'File->New' menu item.

Loading file 1 image

You can load an image into the file 1 position in 2 ways:

  1. Type the path of the file to load into the 'File 1:' text field, and then (a) press the enter key while the cursor is still in the text field, or (b) click the Load button, or
  2. Click the Browse button and choose a file to load from the dialog window which appears. After loading a file in this way, its path will appear in the 'File 1:' text field.

The FITS image contained in the file will then be displayed in the image window.

You can set the image scale by clicking the Manual scale mode button and entering minimum and maximum values into the text fields. Press the enter key after making changes to these values to see their effect.

The minimum value of the image is mapped to black on the screen, and the maximum value is mapped to white. You can reverse this mapping by checking the 'Invert values' button. You can flip the Y axis of the image by checking the 'Flip image' button. You can cause out-of-range values in the image (i.e. values greater than Max, or less than Min) to wrap around in color by clicking the 'Wrap values' button, otherwise out-of-range values are clipped to white or black.

Loading file 2 image

You load an image into the file 2 position in the same ways as for file 1, using the 'File 2:' text field, Load, or Browse buttons. You then set the file 2 image scale, orientation, and color mapping independently from image 1.

Showing image headers

You can show the headers for the FITS images by:

  1. Click in the settings window to select it, then
  2. Choose the 'Window->Show Header 1' or 'Window->Show Header 2' menu items.

Header windows can be resized and scrolled, and the columns can also be resized.

Swapping images

You can alternate the display window between the two FITS images in 4 ways:

  1. Click either the 'File 1' or 'File 2' buttons,
  2. Click the Swap button to alternate the images, or
  3. Check the 'Auto swap' button to automatically animate back and forth between images at a set frame rate. You must set the frame rate (and press enter) before checking the 'Auto swap' button.

      NOTE: Depending on the size of your images, the zoom factor, and the speed and memory of your computer, you may not get the frame animation rate you desire. Rates less than 10 fps are probably best.

  4. Click in the image window to select it, and then press the space bar to swap the images. While the image window is selected, additional presses of the space bar will continue to swap images.

Zooming images

You can zoom (enlarge) both of the images by typing a number into the Zoom text field and pressing enter. Both images are displayed at the same zoom setting. Zoom values must be a positive integer.

Getting mouse values

You can see the image values of each pixel by clicking in the image and then moving (not dragging) the mouse over the image. The cursor will change to a crosshair, and the X, Y and Z (image value) of the pixel under the cursor will be displayed in the settings window. You can stop the mouse tracking by shift-clicking in the image, and the {X, Y, Z} display will remain constant for that pixel.

Setting the circle

You can overlay a circle on both images by checking the 'Show circle' button. The circle is drawn over both images at the coordinates {CX, CY} with a radius = Rad.

You can move the circle across the images in 3 ways:

  1. Type the new coordinates and radius into the CX, CY, and Rad text fields, and press enter after each. Coordinates and radius can be floating-point numbers.
  2. Click the L, R, U, or D buttons to move the circle left, right, up, or down by the amount shown in the text field at center. You can change this amount by typing into the text field and pressing enter. This amount can be a floating-point number, which will move the circle by a fraction of a pixel.
  3. Click in the image to select it, and then press the option key and an arrow key at the same time. Each press of an option-arrow key combination will move the circle by the amount in the text field.

You can zoom the image and adjust the scale settings to better align the circle, to within a fraction of a pixel.

Setting the lines

You can overlay a horizontal and/or vertical line on both mages as an aid for aligning features between images by checking the 'Show h-line' and 'Show v-line' buttons. You can set the locations of the lines by:

  1. Typing the new coordinates into the H and V text fields, and pressing enter. Coordinates can be floating-point numbers.
  2. Clicking the L, R, U, or D buttons. You can change the movement amount by typing into the text field at center and pressing enter. This amount can be a floating-point number.
  3. Clicking in the image, and then pressing the control key and an arrow key at the same time. Each press of a control-arrow key combination will move the lines by the amount in the text field.

Shifting file 2 image

You can align the file 2 image to the file 1 image by shifting it. This can be done in 3 ways:

  1. Type the shift amount into the DX and DY text fields, and press enter after each. Shift amounts can be floating-point numbers.
  2. Click the L, R, U, or D buttons to move the file 2 image left, right, up, or down by the amount shown in the text field at center. You can change this amount by typing into the text field and pressing enter. This amount can be a floating-point number, which will move the image by a fraction of a pixel.
  3. Click in the image to select it, and then press an arrow key (no modifier). Each press of an arrow key will move the file 2 image by the amount in the text field.

The general procedure for aligning image 2 to image 1 is:

1. Align the circle to image 1 as shown above.

2. Roughly align image 2 to the circle by typing integer shifts into the DX and DY text fields, and pressing enter after each.

3. Using the L, R, U, and D buttons, or by clicking in the image and pressing the arrow keys, better align image 2 to the circle by still using integer shifts.

4. Set the zoom factor to 2, and the file 2 shift amount to 0.5. Adjust the file 2 image scale to better see the limb of the planet, and continue using the buttons or arrow key to shift the image by 1/2 pixel. It may help to toggle the circle display on and off with the 'Show circle' button to better see the coincidence of the limb and the circle.

5. Using the Swap button, the 'Auto swap' button, or the space bar (in the selected image), alternate back and forth between image 1 and image 2 to see the accuracy of the alignment. Continue using the buttons or arrow keys to shift image 2 into better alignment with image 1.

6. If necessary, increase the zoom factor to 4, and set the image 2 shift amount to 0.25 pixels, and repeat steps 4 and 5. In general, the zoom factor should be a power of 2, and the image 2 shift amount the reciprocal of this value (although this is not required).

Saving image 2

Once you have aligned image 2 to image 1, you can save it as a new FITS file by selecting the settings window, and then choosing the 'File->Save File2 As FITS...' menu item. This will bring up a standard dialog and save the image as it appears in the image window, including flipping and fractional shifts. The image scale settings will not be saved. The shifted image is saved at a zoom factor of 1x, regardless of the current setting.

Equalizing scale settings

You can automatically adjust the image 2 scale settings so that image 1 and image 2 have the same screen brightness and contrast for easier comparison. To do this:

  1. Check the 'Show subimage rect' box.
  2. Click in the image, and then drag the mouse to create a selection rectangle around the part of the image you would like to equalize. The same selection rectangle is applied to both images, so it is best to at least roughly align the two images first.
  3. Click the 'Equalize images' button. The average screen pixel value and standard deviation will then be calculated for image 1, and the Max and Min settings for image 2 will be adjusted so that it has the same average and standard deviation within the selected area.

Removing video noise

You can remove some of the video noise (e.g. systematic row and/or column noise such as alternating light and dark lines) by using fractional shifts. For example, the alternating row noise can be attenuated in image 2 by using shifts of 1/2 pixel:

Thus, while it may be be more accurate to align images using integer shifts, you might consider using a fractional shift to eliminate some of the electronic noise present in the image, especially if you are then planning to stack several shifted images to make a composite. Part of our Venus image preprocessing involves shifting each image 0.5 pixels left and right, and averaging the results, and then shifting 0.5 pixels up and down, and averaging the results, to remove such noise.

Using keyboard commands

To summarize, keyboard commands available when the image window is selected are:

  1. Arrow keys move image 2.
  2. Option-arrow combinations move the circle.
  3. Control-arrow combinations move the lines.
  4. Space bar swaps images.

Multiple image alignment procedure

Frequently it is necessary to align several set of images to each other for stacking, or for inter-sequence comparison (e.g. for feature motion analysis). A procedure we have used for aligning 70 512x512 pixel images of Venus into 7 sets (each set acquired at a different observation time) was the following:

1. Align the first image, also the sharpest, so that it is centered in the frame at (255, 255). This was done by loading the image into the file 2 position, and then shifting until it was centered in a circle located at (255, 255). We used a zoom factor of 2, and a file 2 shift increment of 0.5. Image features used to perform the alignment were the top and bottom cusp of the bright crescent, and the edge of the dark limb. Once this image has been aligned, it was saved to disk. This first step provides the reference to which all subsequent images will be aligned.

2. Load the aligned first image into the file 1 position, and load the second image of the same time interval into the file 2 position. It should be noted here that images yet to be aligned were done so with their Y axis flipped, while already aligned images are viewed unflipped (since thay have been saved flipped and shifted).

Using integer shift, perform a rough alignment of the second image. Then, using the buttons, set to 0.5 pixel increment values, iteratively move the second image until it aligns with the first. You can press the 'Swap' button to see the difference between images, or check the 'Auto swap' box to continuously animate between images as you continue to align.

As with the first image, features used to register the two images include the top and bottom cusps of the bright crescent, and the edge of the dark limb. However, since these two images were acquired at about the same observing time, there should be no perceptible cloud motion between them. Therefore, you can also use any variation in the cloud motion (left-right or up-down), to adjust the registration. Make sure that you are looking at the cloud features themselves, rather than the background noise of the image (e.g. bad pixels, non-flat-field variations in brightness), all of which will also appear to move. When the images are properly aligned, the clouds will not move, although the background noise may continue to do so.

It may not be possible to align the images based on all the aformentioned criteria, due to issues which will be discussed below. Proper alignment of one part of the image may not entail proper alignment of another part of the image. Nevertheless, it should be possible to adequately align overall images to within 0.5 pixel or better. If you use a smaller shift increment, it is suggested that you keep to powers of 2 (e.g. 0.5, 0.25, 0.125, etc..).

When this image is aligned, it is saved to disk.

3. Repeat step 2 for all other images in the current time interval. That is, subsequently align all other images to the first (best) image of the interval, not to the previous image of the interval.

4. Repeat step 2 for the first (best) image of the next time interval. That is, align the first image of the next interval to the already aligned first image of the previous interval.

5. Load the aligned first image of the new time interval into the file 1 position and then repeat step 2 for each additional image of the new time interval.

6. Repeat steps 4 and 5 for the first and remaining images of each additional time interval.

Alignment issues

Image alignment is very much a subjective trial and error procedure, and there are several issues which confound the alignment process. For example, it has proven to be extremely difficult to create automated software which can accurately align images without human intervention, often because they cannot unambiguously distinguish the gray, fuzzy, noisy limb from the gray, fuzzy, noisy background. Neither the limb nor the background maintain a constant brightness along the circumference. Several different algorithms have been tried, and each is accurate to within a pixel or so. However, all automated techinques so far have required manual tweaking of final alignment in order to stack images.

Although noise in the images certainly contributes to the poor performance of an automated approach, there are two additional factors, intrinsic to the images themselves, which appear to be at work:

1. The overall quality of images changes from file to file, even over a time period of only a few seconds, and there can be a great variation in the computed and perceived sharpness of images within the same time interval. This variation in sharpness makes it difficult for both human and machine to find and recognize features between images, as their location and geometry can change by a pixel or more. This variation is presumed to be due to changes in the Earth's atmosphere and in the optical system. These changes appear to have timescales ranging from only a few seconds to those lasting the duration of the observing night or morning. It may not be possible to alleviate these non-systematic effects, although an attempt at some kind of semi-blind deconvolution to reverse the effects of unknown but obviously active distortion PSFs may be worthy.

2. The magnification of images changes from file to file, in a non-isotropic fashion with independent X and Y values. This has the effect of distorting the planet disk from a circle, with the consequence that all parts of the image cannot be aligned at the same time. Often a choice must be made whether to align on the top or the bottom cusp --but not both--, or on the limb or the clouds --but not both--, or on the edge or the center of the planet --but not both. It might be possible to restore the symmetry of the disk by performing separate X and Y magnification transformations, using the fast Fourier transform. Procedurally, this might entail first aligning some part of the cusp, limb, or clouds, and fixing that point between images. Then, by minutely adjusting both the X and Y magnifications while maintaining the aligned point, independently bring other points of the planet first into X alignment, and then into Y alignment. Future versions of FITSRegister may add this feature, so that the alignment process would involve adjusting 4 parameters for DX, DY, MX, and MY between pairs of images.

Setting default settings

You can automatically fill in some of the settings in a new FITSRegister document if you create a text file called FITSRegister.defaults.txt and place it in the same folder as the FITSRegister application. Here is an example of such a file:

file = /Users/sky/Projects/SWRI/Venus/New071304/aligned/1230.fits
max = 4e3
min = 300
zoom = 1
flipped = 0
cx = 255
cy = 255
rad = 169
shift = 1

file2 = /Users/sky/Projects/SWRI/Venus/New071304/aligned/3465.fits
max2 = 4.5e3
min2 = 650
flipped2 = 0
dx = 0
dy = 0
shift2 = 0.5

You will want to replace the file and file2 strings by paths to images on your computer. The syntax of this file should be pretty obvious. shift is the shift value for the circle, and shift2 is the shift value for image 2. You should save the FITSRegister.defaults.txt file with Unix line endings (i.e. '\n'). If it exists, this file will be used to initialize all new FITSRegister documents.

Saving/loading documents

You can save the current values of settings in a FITSRegister document file by choosing 'File->Save As...' when the settings window is selected. Then, when you next run FITSRegister, you can reload these settings by choosing 'File->Open'. Your images will not be saved in the FITSRegister file, but they will be reloaded, flipped, shifted, and zoomed from the 'File 1:' and 'File 2:' strings, and other control values, if possible.

İSky Coyote and Dr. Eliot Young, 2006