stella

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 parametesr of those stars in the image. The output files includes 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 serach 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 wtihin 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. The XXXX is a four-digit number that is somehow related to the ID of the star in the image.

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

Running an image through stella: manual shift

Here are the commands you could use 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. The next section shows what this would look like if you had to manually shift the image.

Using stella

Here are the commands you could use 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.

2. Use COVERAGE.TXT as an input to shape2mapsA

shape2mapsA
SHAPEFILES/COVERAGE.TXT

3. Use view_shapeA to visualize the coverage on the shape. Note that if you only run view_shape, you will not see the coverage.