stella

Category DART

Version 1.0

Description

Stella is a program that matches up stars in images with stars in the Tycho2 star catalog and records information about the locations and other parameters of those stars in the image. The output files include information on the positions of the stars in the image, how well the stars correlate, and some rough information about the brightness of the stars in the images vs. the magnitudes of those stars in the Tycho catalog.

To use stella, users give the program the name of an image to use. The program uses SPICE kernels to figure out where that image is looking. It compares the predicted locations of stars in a star catalog to the locations of stars in the image. The program finds stars by correlating the stars in the image against a gaussian at the predicted location of the star.

The user specifies how bright the star must be to be considered, how far apart the stars need to be to avoid confusing one star for another, how far from the predicted location the star can be, whether to despeckle the image, the assumed point-spread function for the gaussian, and an aperture for summing up brightness intensity. The program has a routine to autocorrelate the stars in the image to gaussians representing the predicted star locations. If the stars are too far off to autocorrelate, then the user can enter a manual shift for several stars. Typically after a few stars have been shifted, the rest of the stars in the image will autocorrelate.

One can run stella multiple times to increase the numbers of stars found in the images. The first time, limit the search to bright stars, a large search region, and a larger correlation limit. Once those bright stars have pulled the image into place, you can re-run stella with dimmer stars (i.e., using a larger magnitude cutoff), a smaller search area, and a lower correlation limit to find additional, fainter stars.

After stella has been run on multiple images, you can use the REG files to compute a distortion model for the camera. Those files are used by a program called distortion to compute a K matrix and distortion model for a camera. The solved-for K matrix and distortion parameters can then be entered into make_sumfiles.txt and INIT_LITHOS.TXT, respectively, for use in SPC. A separate page describes the program DISTORTION. In practice, you run a few images through stella and then use those REG files in distortion to come up with an initial update to the camera model. Those first few images may require a lot of manual shifting. Then you put those updated parameters into make_sumfiles.txt and INIT_LITHOS.TXT so that when you run more images, more of them with autocorrelate. Then you re-run distortion with that larger set of images to refine the camera model.

Input Files

./INIT_LITHOS.TXT Core SPC file
./make_sumfiles.txt Core SPC file containing kernel, camera, and sigma information
./make_sumfiles.in Core SPC file containing mapping between file name and SPC name
./IMAGESFILES/PICNAME.DAT The picture that stella will process
./quaternions.txt Optional file. Ask Bob for details. Appears to be OREx specific.
./REGFILES/PICNAME.REG Contains pointing information and pixel/line locations of stars in the image. If a .REG file exists, then stella will use that as the initial guess of the star locations. But, the first time you run stella, you will not have a REG file, and that's fine. Each time you run stella, a new REG files overwrites the old one. If you want to start fresh on an image, you will need to delete the existing .REG file before starting stella.
/usr/local/spc/stars/*dbk Star catalog

Output Files

./REGFILES/IMAGENAME.REG See above
./MAGFILES/PICNAME.MAG A file containing information about the stellar magnitude and summed DN intensity within an aperture of qsize QSZ
./CORRPLOTS/corrplotXXXX.txt A file containing information about how well each star in the image correlates. All of the files in the directory are overwritten each time you run stella.

Note: Stella writes one REG file and one MAG file for each image. If stella correlates no stars in the image with stars in the catalog, then it does not write out REG or MAG files. Stella writes one corrplot file for each star in a given image.

Prerequisites

You need to have compiled stella.f and distortion.f. These are included in the DART-Updates branch of the blessed code in GitHub.
You need to have STARS2019 copied to /usr/local/spc/stars/
You need an SPC directory with CORRPLOTS, MAGFILES, and REGFILES directories.
You need an INIT_LITHOS.TXT
You need a make_sumfiles.txt
You need to have run PROCESS_FITS to make .DAT files. (You do not need to have run make_sumfiles.)

Important parameters

Stella uses a few different parameters to help find and correlate the stars in images with the stars in the catalog. These parameters are:

MAX MAG. This is the maximum magnitude (i.e., the dimmest star) that stella will search for. Dimmer stars will have lower correlation scores than brighter stars, and when you are first starting out it is helpful to focus on brighter stars. For DART, we have been using 11 as a starting point. Once we have a good number of stars in the image, we will re-run the image using a maximum magnitude of 11.5. You can't go any dimmer than 12 due to the nature of the Tycho2 catalog.
PROX LIM (pixels). This sets how close stars can be together and still be used. It is measured in pixels. If the stars are too close together, then stella might confuse one star for another when trying to align the stars with the image. That would be bad. So, you want to set PROX LIM to be large enough that you don't confuse one star for another, but not so large that you end up with only a few usable stars. 10 is a good number: stars must be at least 10 pixels apart for stella to use them.
DESPEK (0/1). This determines whether stella will apply a despeckle routine to the image. For DART, we have not been using the despeckle option, and I have not played around with it.
RZLM. Residual limit. This is a limit (in pixels) on how far the star in the image can be from its predicted location in the star catalog. Using a larger number here will allow stella to automatically find stars that are far away from where they should be. The risk, however, is that you grab the wrong star, which would be bad. Using a smaller number makes it less likely that you will grab the wrong star, but more likely that stella won't autocorrelate and that you'll have to shift the image manually. For DART, we used a larger number (20) combined with brighter stars (max mag = 11) for the initial search. Then we did a finer search (RZLM = 5, max mag = 11.5) once we had things initially aligned using the brighter stars.
CRLM. This is a correlation limit. This is not really the correlation but the correlation times the sd of the signal so if a star is really dim it can be really small even if the actual correlation is reasonable. Stars must correlate with a value greater than or equal to this in order to be added to the REG file. Dimmer stars will have lower correlation scores, even if they are in the right place. So, you have to adjust the correlation limit based on the maximum magnitude that you set. (It also makes sense to require a higher correlation limit when you are allowing a larger RZLM so that you avoid correlating with the wrong star.
PTSPD. This defines the point-spread function (PSF) of the Gaussian that will be used to correlate the star positions in the catalog with stars in the image. It has nothing to do with the PSF of the camera.
KMX (le 25) This is a search range for star/template overlap (template = the gaussian used to fake the star in the star catalog). A bigger number searches over a larger area, but if you search too large of an area, you might get erroneous correlations. With fewer stars (a lower magnitude cutoff) and a stricter correlation limit, it's safe to use a big search radius. But, with more stars and a lower correlation limit, you want this to be smaller.
QSZ (le 10). This defines the radius of a circle (in pixels) that is used to look at the integrated DN over the star. Changing the qsize changes the size of the "aperture" over which all the DNs in the pixels are summed. This is a quick and dirty way of doing aperture photometry.

For DART, we settled on a two-step process. The first step did a big search for bright stars. The second step (which used the .REG file from the first step as a starting point) used a smaller search that included dimmer stars.

big search: 11.0 10 0 20 .01 1.14 20 6
small search: 11.5 10 0 5 .01 1.14 5 6

Running an image through stella

Here is an example of how to run stella on an image called D696096913G0. In practice, these particular commands would not work well if you haven't already gotten an initial update to the camera model. But, these are convenient for describing the various inputs. A later section of this page shows what this would look like if you had to manually shift the image.

stella                    invoke the program
D696096913G0              provide the name of the image you want to run
n                         no, you do not want to use quaternions
11.5 10 0 5 .01 1.14 5 6  these are parameters that control the star search. 
1024 1024                 image dimensions. We don't have sumfiles (and will never have sumfiles for star images), so we must specify this each time so that SPC knows how big to make the image.
                          After entering these image dimensions, stella will make TEMPFILE.ppm and TEMPFILE.pgm. TEMPFILE.ppm is the more useful. Both images have a square-root stretch applied
                          to them to bring out the dimmer areas. Using the autolevels in Graphic Converter helps bring out the stars. 
0                         yes, you want to continue
y                         yes, solve for pointing
y                         yes, autocorrelate. Note that stella doesn't complain if stars don't correlate. It's not like lithos where you get ***** to help you at-a-glance.
                          Instead, you have to rely on other means. In TEMPFILE.ppm, the stars would still be offset from their crosshairs, and the .REG file wouldn't have any 
                          stars listed in it. (If no stars are found, period, then you won't get a .REG file.)
1024 1024                 then we enter the same things to do three more "iterations" for autocorrelation
0
y
y
1024 1024
0
y
y
1024 1024
0
n                         no, don't solve for pointing. This will end the program.

Here is that same image, with the same inputs, but including the questions/prompts that users must respond to.

stella         
           
ENTER PICNM
  D696096913G0    

Use quaternion? (y/n)          
  n      
                   
INPUT MAX MAG, PROX LIM (pixels), DESPEK (0/1), RZLM, CRLM, PTSPD, KMX (le 25), QSZ (le 10)
  11.5 10 0 5 .01 1.14 5 6  

Enter NPX, NLN
  1024 1024  

0. Continue
1. Toggle BW (.pgm) markers --> if you choose this option, then the .pgm file will have crosshairs overlaid on it
  0                         --> to show the star positions. The .ppm file already has this overlay +  more star info.

Solve for pointing? (y/n)
  y                         

Autocorrelate? (y/n)
  y        

(repeat the 1024 1024/0/y/y twice more)

Enter NPX, NLN
  1024 1024

0. Continue
1. Toggle BW (.pgm) markers
  0

Solve for pointing? (y/n)
n

Stella prints a lot of information to the screen as you run the program. Here is a page with the saved Terminal output from a stella run. That page has descriptions of all the things that stella prints to the screen.

Using a manual shift

Often when you first start, you will need to manually align the image. To do this, you would enter the following after the first time you enter the image size:

 Solve for pointing? (y/n)
y
 Autocorrelate? (y/n)
n
 Autocorrelate after move? (y/n)
y

Stella then prompts:

 Enter observations. I for ignore, Q for finish
Predict =     643.54    906.60
 Enter observation

By "observation", stella means "star". The "Predict" is the predicted pixel/line location of a particular star in the image. This is the center of the red cross hairs for the star in question. So, first you must find that particular star in the image. stella goes from brightest star (lowest magnitude) to dimmest star (lowest magnitude), so the first observation will correspond to the brightest star in the image. TEMPFILE.ppm lists the name of the star in the star catalog and the Vmag on the bottom and top, respectively, of each set of crosshairs. You need to enter the pixel/line location of the corresponding star in the image. If the star is saturated, you don't want to use it, so just enter "I". Stella will ignore that star and move on to the next one. After you have entered two or three stars, enter "q" to quit. (Two or three stars seems to be enough to pull things into place, in my experience.) Entering "q" here doesn't quite the program, it just quits you out of that little section of the program where you are manually entering the pixel/line locations of the stars. Stella will then prompt you to enter the image size. After you do that, check TEMPFILE.ppm and see if things are lining up better. If they are, then try autocorrelating and recheck TEMPFILE.ppm. If the stars still aren't in the crosshairs, then try shifting a few more stars. Here is an example of entering multiple stars into stella manually:

 Enter observations. I for ignore, Q for finish
Predict =     643.54    906.60
 Enter observation
643 906
        13    643.81    905.98      0.96      0.13      9.50
Predict =     908.33    630.22
 Enter observation
908 630
        21    908.22    630.32      0.92      0.15      9.82
Predict =     480.65    652.37
 Enter observation
480 652
        23    480.76    652.62      0.89      0.11      9.82
Predict =     775.91    113.56
 Enter observation
q

Once you quit out of the manual step, do a couple of fitting iterations before closing the image out. By the time things autocorrelate, you only need two or three fitting iterations to converge.

Using stella in practice

It is helpful to have TEMPFILE.ppm open in Graphic Converter when you're running stella. You will refer to TEMPFILE.ppm often, and you will need to be able to read off the pixel/line locations of stars in the image.

1. Select ~10 images. You will process these images, potentially having to do each one manually, in order to get an updated camera model that will make the additional images more automated.

2. Start with the first image, and see if it autocorrelates. Invoke stella, enter the name of the image, and then copy/paste the following in Terminal. This assumes the images are 1024x1024, like they are for DART.

n
11 10 0 20 .01 1.14 20 6
1024 1024
0
y
y

3. See whether it autocorrelated successfully. To do so, look at TEMPFILE.ppm. The next action depends on whether autocorrelation worked. Compare the positions of the stars in the image with the red cross hairs that show where the stars should be. If autocorrelation worked, then the stars should be centered in the red cross hairs. If autocorrelation failed, then the stars will not be centered in the crosshairs.

3a. If the autocorrelation worked, copy/paste the following into Terminal, confirm that the stars are in the cross hairs in TEMPFILE.ppm, go back to step 1, and proceed with the next image.

3b. If autocorrelation failed, then you will need to manually shift the stars. Enter the following

Then you will need to manually enter the correct pixel/line location, as described in the section "Using a manual shift". Enter three stars, and then enter q to quit. Enter the size of the image again, and then look at TEMPFILE.ppm. If the stars are in the crosshairs, then go ahead and use autocorrelate. Enter 0/y/y and then copy/paste the commands under 3a to finish the image. Confirm that the stars are in the cross hairs, and then move on to the next image.

4. After processing those ~10 images, remove any REG files with fewer than 7 stars (REG file >1 KB), run distortion, update the K matrix in make_sumfiles.txt, and add the distortion parameters to INIT_LITHOS.TXT. See the documentation for distortion for details on how to do that.

5. Run the remaining images as through a two-step process that uses a big search with brighter stars to do an initial alignment, followed by a second round with a smaller search area and dimmer stars so that you get more samples across the image. If any images fail to autocorrelate in the first step (either no REG file or a REG file <2 KB), then run those by hand before proceeding to the second round.

6. After all images have been processed through both steps, re-run distortion and update make_sumfiles.txt and INIT_LITHOS.TXT with the final camera model.