stella

Description

Stella is a program that matches up stars in images with stars in a 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.
• /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.)

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.

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. More details below.
1024 1024                 image dimensions. We don't have sumfiles, so we must specify this. 
0                         yes, you want to continue
y                         yes, solve for pointing
y                         yes, autocorrelate
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
  0                         

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.

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.