This program takes a photometry file, with astrometry, provided by earlier routines and incorporates the stellar measurements into the photometry database. This routine does NOT try to calibrate or check the photometry, nor does it try to improve the coordinate determinations or calculate chisquares for position or photometry - those tasks are performed by other routines.

Addstar starts by loading in the photometry file and converting the pixel coordinates to sky coordinates using the astrometry information in the header of the file. It also gets the detection limits and stores the image astrometry information.

Next, addstar determines which of all the previous images overlaps with this image and also which of the catalog regions overlaps with this image.

Addstar considers each catalog region in turn, and compares the positions of stars in the catalog with stars in the image. If a catalog star is detected, a new measurement is added to the catalog. If a catalog star is not detected, but is in the field of view of this image, the detection limit for this image is added to the list of measurements as an upper limit. If the image contains a star which is not already included in the catalog, the star is added to the catalog, and all previous images are checked to see if they included this location. If so, upper limits are added to the list of measurements.

To deal with blended images, we have taken the philosophy that all measurements compatible with the coordinates of a given star should be included in the list of measurements. This assumes that programs or people downstream will figure out which is the "correct" measurement. To this end, if a catalog star is consistent with multiple measurements, they are all added to the catalog measurement and the measurements are given a flag to say that there was blending in the catalog (ie, it is probably the catalog star which is a blend). If multiple catalog stars are consistent with the same image star, that measurement is added to each catalog star, and given a flag to say that there was blending on the image.

After all catalogs have been checked, updated, and written to disk, the image is added to the database of images.

see DVO database for discussion of the database storage format.

## Usage

     addstar (filename)
     addstar -cat (catalog)
     addstar -ref (filename)

In the first form, addstar loads the photometry information for a single image into the database. The file must be in one of the Elixir cmp/smp/smf formats, and must have been astrometrized (eg, with gastro, gastro2, and/or mosastro). The file must also be provided with a valid photcode in the header (keyword PHOTCODE) or the photcode must be supplied as an option to addstar (see below). The photcode must be listed in the photcode table (see config variable PHOTCODE_FILE). In the case that the image has been astrometrized with mosastro (two-level mosaic astrometry), the corresponding mosaic header unit must be supplied as an option (see below).

In the second form, addstar will load photometry from the specified reference catalog, located in a known location, and will load it into the database. Allowed catalog names are: `USNO, GSC, 2MASS, 2MASS-ALLSKY, 2MASS-DR` . Note that USNO corresponds to the USNO-A catalog, 2MASS corresponds to the 2MASS-ALLSKY catalog. It is necessary to have defined an appropriate photcode for the given catalog. The following photcodes are expected to exist:

catalog | allowed photcodes
--- | ---
GSC | GSC_M
USNO | USNO_RED, USNO_BLUE
2MASS* | 2MASS_J, 2MASS_H, 2MASS_K

When more than one photcode is allowed, one must be selected; there are no defaults in that case. It is advised that addstar -cat be used with a restricted region of the sky; the default behavior will load the reference catalog for the entire sky into the DB!

In the third form, addstar will load data from the specified ASCII text file with a fixed format. The file must contain lines with one line per star. The first four columns must contain the values RA, DEC, Magnitude, Magnitude error. The RA and DEC must be in J2000 decimal degrees. Blank lines are allowed, and lines may be commented with the hash sign (#). The provided photometry must all be for a single photcode, which must be provided as a command-line option.

## Additional Options

      -region ra ra dec dec           : only add data in specified region (-ref mode only)
      -p (photcode)                   : specify photcode (override header)
      -time (YYYY/MM/DD,HH:MM:SS)     : specify date/time (override header)
      -mosaic (filename)              : identify associated mosaic frame for chip image
      -fits                           : input file is FITS table, not TEXT table
      -existing-regions               : only add measurements to existing catalog files
      -only-match                     : only add measurements to existing objects
      -missed                         : skipped 'missed' entries
      -replace                        : replace time/photcode measurements (no duplication)
      -image                          : only insert image data
      -cal                            : perform zero-point calibration
      -skyprobe                       : specify skyprobe mode
      -2massquality                   : define 2MASS quality flags to keep
      -accept                         : accept bad astrometry from header
      -force                          : force read of database with inconsistent info
      -v                              : verbose mode
      -dump (mode)                    : output test data
      -help                           : print this list
      -h                              : print this list

## Elixir Configuration Data

addstar uses the following Elixir configuration variables:

- EXPTIME-KEYWORD : header keyword defining exposure time
- DATE-KEYWORD : header keyword defining the date
- DATE-MODE : mode for header date information: use a combination of Ys, Ms, Ds to specify order. If only 2 digits are specified for the year, numbers greater than 50 are assumed in the 1900s, less than in the 2000s. eg YYYY/MM/DD
- UT-KEYWORD : header keyword defining UT
- MJD-KEYWORD : header keyword defining MJD
- JD-KEYWORD : header keyword defining JD
- AIRMASS-KEYWORD
- CCDNUM-KEYWORD
- ST-KEYWORD
- RADIUS : radius for matches; may have the value "header", in which case the astrometric error listed in the header, along with `NSIGMA` is used to define a match. Otherwise, defines a radius in arcseconds.
- NSIGMA : number of astrometric error sigma to use for match radius (see `RADIUS`).
- XOVERSCAN : used to define valid pixels in the image. subtracted from image NAXIS1 value to define image box.
- YOVERSCAN : used to define valid pixels in the image. subtracted from image NAXIS2 value to define image box.
- ADDSTAR_XMIN : this value, and the following three, are used to define a region on the image where the photometry is considered reliable. Stars outside this region are marked as having poor measurements.
- ADDSTAR_XMAX : see `ADDSTAR_XMIN`
- ADDSTAR_YMIN : see `ADDSTAR_XMIN`
- ADDSTAR_YMAX : see `ADDSTAR_XMIN`
- MIN_SN_FSTAT : only include objects in the DB with S/N greater than this value.
- GSCDIR : location of the HST Guide Star Catalog
- USNO_CDROM : location of the USNO-A data
- 2MASS_DIR_AS : location of the 2MASS allsky data
- 2MASS_DIR_DR2 : location of the 2MASS DR2 data 2MASS, USNO, and GSC are all loaded from their idiosyncratic formats.
- GSCFILE : location of the GSC layout file (for GSC and ptolemy)
- CATDIR : location of the ptolemy data
- IMAGE_CATALOG : location of the image database table
- CATMODE : storage mode for the database. may be one of RAW, MEF, SPLIT, MYSQL. SPLIT and MYSQL are currently unsupported. This defines the output format for new tables; the input format is auto-detected.
- CATFORMAT : data format for the database. may be one of LONEOS, ELIXIR, PANSTARRS.
- PHOTCODE_FILE : location of the photcode file describing the photometry system of interest.
- OBSERVATORY-LATITUDE : hard-wired observatory latitude. used for precision airmass for skyprobe. should be replaced with a more sophisticated approach
- SUBPIX_DATAFILE : table for subpixel structure corrections (skyprobe)
- IMAGE_CATALOG_TEMPLATE : deprecated, was used to supply a FITS header template
- CATALOG_TEMPLATE : deprecated, was used to supply a FITS header template