stella
Category DART |
Version 1.0 |
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 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.
where smin is the minimum maplet scale in km you wish to include, smax is the maximum maplet scale in km you wish to include, tol is a search range along surface normal (i.e., how far to search for a maplet; same idea as densify), and minpic in the minimum number of pictures. If set to 0, then all maplets will be considered.
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.