# Astrometry

An astrometry calibration of FITS frames.

## Synopsis

`munipack astrometry [.. parameters ..] file(s)[,result(s)]`

## Description

Astrometry action derives astrometry calibration of FITS frames (Overview).

Astrometry is naturally separated on two parts:

- Matching where the correspondence between stars on frame and in catalogue is established. The matching can be done without knowledge of any transformation, when very general presumptions are supposed (the coordinates are Euclidean).
- Astrometry transformation is computed by using of robust algorithms.

### Reccomendations

The matching process is searching for a mutual correspondece in two list of coordinates. The mathcing is generaly slow and complex process. To increase of its reliability and speed, is is important to compare (and prepare) the list by such way so that the coordinates as well as magnitues overlaps. The overlap in coodinates means to use of catalogues selection with very similar centre and radius as the frames. Also magnitude overlap must corresponds with non-saturated (and non-faint) stars on images. (If both the conditions will not meet, the matching will probbaly also sucessufll.)

There two ways how to realise. The coordinate correspondece can be make with known object position and field of view (FOV) of telescope (it means angular diameter of the cone on sky) in degress. If the telescope has FOV 0.5 deg and the observed objects is Crab nebulae than the optimal selection from UCAC4 cataloguje is:

      munipack cone -r 0.2 -- 83.63 22.01

The magnitude selection is simliar. It depends on all telescope, exposure time and filter. The mathcing (as well as photometry) will sucesfull only with non-saturated bright stars. If we have an experinece that the stars are saturated at 12, than the catalogue selection can be improved (syntax is column_name=[some constrain]):

      munipack cone -r 0.2 --par 'f.mag=>12' -- 83.63 22.01

Alternatively, the filtration capabailities of FITSIO can be used

      munipack astrometry -c 'cone.fits[1][$f.mag$>12]' crab.fits

We are selecting only non-saturated stars fainter than magnitude 12 in column f.mag. The usual linear range of 16-bit CCD cameras is about 3-5 magnitudes.

Parameter --maxmatch slices the catalogue on parts with similar magnitudes (magnitudes in certain range). This is due to sorting of both catalpogue and frame by magnitudes.

Parameter --minmatch sets minimal length of match sequence which is supposet to by complete (sucesfull match). For sparse fileds, the defaults are usually satisfactyory, but very dense fields like SMC, LMC needs increase this parameters. Munipack sets the default of 5. If the mean surface density exceeds the limit (?), the parameter is increased. The small values on crowded fiedls can produce false match (because probability of miss-match is getting appreciable).

Suitable parameters for astrometric calibration
Case | Solution
--- | ---
sparse field, < 1 m telescope | defaults
crowded field, < 1 m telescope | --minmatch=7, --maxmatch=44
sparse field, > 1 m telescope | -c 'cone.fits[1][$f.mag$>14]'
crowded field, > 1 m telescope | `--minmatch=7, --maxmatch=44, -c 'cone.fits[1][$f.mag$>14 .and. $f.mag$<20]'`

## Algorithm

Lets we denote the reference star coordinates as the catalogue and coordinates of detected stars as the frame.

The following algorithm is used for matching:

- Catalogue coordinates are projected to rectangular. The projection can be set with `-p,--projection` switch. As the centre of projection all stars computed as arithmetical mean is selected.
- Frame coordinates are pre-scaled to lie in interval 0 .. 1 and to have origin in centre of frame (the projected and measured coordinates has similar scale and origin after this transformation to improve numerical precision).
- Twines of stars in catalogue and in frame are get as the starting step of matching algorithm.
- To get a next star in sequence, the following function (in a meta-language) illustrates the principle:

      Function Sequence for next star
        For all unused stars in catalogue:
           Compute u1,v1
           For all unused stars on image:
              Compute u2,v1
              Is Acceptable and distance({u1,u2} and {v1,v2}) < limit?
                  Has the sequence required length?
                    Got Solution!
                  Call Sequence for next+1 star
                  Did fail the Sequence?
                    Skip the star
      End function Sequence

  Variables u1,v1 and u2,v2 are coordinates of in a triangle space of a triplet of stars. The distance is distance in triangle space.
- Implemented algorithm includes additional tests to be sequence acceptable:
  - the sequence length and limit for objects used to matching can be changed by `--minmatch, --maxmatch` parameters
  - The limit is set via `--sig` parameter which sets σ expected error in the coordinates of stars. The parameter is also used for estimation of tolerances of angles.
  - Angles computed between all stars in a real space must be inside tolerance.
  - the sequence must have first and last stars connected (all implemented tests must be passed).
  - To prevent use of degenerated triangles (for sides a+b≈c), only triangles with the v > 1 + σ - u are used.
- The first sequence, which is successful found, stops matching. When `--full-match` is used, it is scan throughout all possible twines. In this case, the sequence with the best parameters is used. The full scan can take a lot of time.

An alternative sequence can be constructed from known transformation and the astrometry is just more precise.

The known sequence of stars can be used to determine astrometry transformation:

- The coordinates of catalogue stars are corrected for its proper motion (only when `--col-pm-ra, --col-pm-dec`) is set
- Initial estimation of parameters is computed by minimising of absolute deviations.
- The corresponding stars in catalogue and frame are found by searching for stars in close neighbourhood (practically, the `--match nearly` is performed.
- The transformation is determined with all possibles stars by the robust minimisation.

The matching needs at least of tree stars (to construct of a triangle. The astrometry algorithm needs at least 5 stars (for 4 parameters) but has lower-count alternative with minimum of two stars. Generally, the astrometry has recommended minimum of 7 stars, but ideal is over 20. Any modern (like Munipack default UCAC5) catalogue has more reference objects on medium crowded fields.

## Prerequisites

The calibration needs both detected stars and instrumental photometry.

## Input And Output

On input, list of frames containing the table with already detected stars and photometry is expected.

On output, the WCS calibration in the header of primary FITS is created (or updated) for all input images.

## Parameters

### Modes of Calibration:

`-m, --mode [=mode]`
  Mode of calibration:
  - `match` (default),
  - `sequence`
  - `manual`

### Reference sources:

`-c, --cat file.fits`
  reference catalogue in FITS format, if none of `-c, -r, -R` is presented, the default `cone.fits` is used as -c cone.fits
`-r, --ref file.fits`
  reference frame (already calibrated frame)
`-R, --rel file.fits`
  relative to the reference frame (no projection)
`--col-ra label`
  Right Ascension column in catalogue, default: `RAJ2000`
`--col-dec label`
  Declination column in catalogue, default: `DEJ2000`
`--col-pm-ra label`
  Proper motion in Right Ascension column in catalogue, default: `pmRA`
`--col-pm-dec label`
  Proper motion in Declination column in catalogue, default: `pmDE`
`--col-mag label`
  Magnitude-like column in catalogue, default: `f.mag`

### Manual Calibration Parameters:

`-p, --projection [=type]`
  projection:
  - none,
  - gnomonic (default)
`--xcen xxx.y`
  centre of projection on chip [pix] (default: width/2)
`--ycen xxx.y`
  centre of projection on chip [pix] (default: height/2)
`--rcen ddd.ddd`
  centre of projection in Right Ascension [deg]
`--dcen ddd.ddd`
  centre of projection in Declination [deg]
`--scale ssss.s`
  scale [deg/pix]
`--angle aa.aaa`
  angle of rotation [deg], clockwise positive
`--reflex`
  set whatever the frame is reflected

### Parameters For Fit:

`--fit [=fit]`
  method used for fitting of star positions:
  - squares (standard least-squares),
  - robust (by default).

### Parameters For Matching:

`--sig xxx.y`
  mean uncertainty in coordinates of objects on frames in pixels,default is 1 pixel
`--sigcat ddd.ddd`
  mean uncertainty in coordinates of objects in catalogue in degrees, default is 1 arcsec
`--fsig d.d`
  flux errors, default is 1 which fits common observation conditions (clouds, wrong filter). Very bad bad observations may require larger values. The parameter significantly affects matching speed.
`--minmatch n`
  Sets count of objects in match sequence. Default is 5. Crowded fields will require increase the value on 7 or more. The extremely sparse fields with a few stars only will enough 3-5. To use match algorithm minimal length is 3. Upper limit is given by `--maxmatch`.
`--maxmatch n`
  Set maximum count of objects for matching. The default is 33 or count of objects in catalogue or in frame. There is no upper limit, but values over hundredth are probably unusable. The recommended value for crowded field is 30 - 50.
`--luckymatch n`
  Set the number which is added to value given by `--minmatch` and supposed to indicate a reliable sequence. For instance, `--minmatch 5` and `--luckymatch 3` indicates good match when result has at least 8 successful matches. Default values is 3. It is reliable like full match and fast like use of first successful match, if the value is greater than 1.
`--disable-lucky-match`
  Finish at first success match when `--minmatch` is reached. Alias for `--luckymatch 0`
`--enable-full-match`
  without this option finish when a first successful lucky match has occurred. Full matching is performed when presented, eg. the matching algorithm explores all possible and acceptable combinations of stars.
`--disable-flux-check`
  To improve speed and reliability of matching, fluxes are used as the additional independent quantity for checking. This switch disables flux check completely. A possibility of mismatching will increase, especially on crowded fields.
`--disable-rms-check`
  Normally, RMS (in pixels) is smaller that xsig*dig (in pixels) for successful fit and one is on condition for the calibration. This option disables the test and must be used very carefully. Useful in cases when statistical errors are insignificant to systematical ones (due to an improper projection).

### Miscellaneous:

`--units`
  output units: deg, arcmin, arcsec, mas, pix and auto (default)
`--disable-save`
  disable save of calibration to header
`--remove`
  remove calibration from FITS header (keywords like CTYPE, CRPIX, CRVAL, .. and the detailed log)
`--show-defaults`
  show default values of parameters

See Common options for input/output filenames.

Following combinations of mode and options are possible
Mode | Options
--- | ---
`match` | `-c, -r, -R,` Parameters for Matching
`sequence` | `--seq1, --seq2, -c, -r, -R`
`manual` | `--projection, --xcen, --ycen, --rcen, --dcen, --scale, --angle, --reflex`

For manual calibration, use `--projection, --xcen, --ycen, --rcen, --dcen, --scale, --angle` and don't use `-c, -r, -R`. The parameters are just interpreted in WCS framework and stored to FITS header.

If an astrometry calibration is already presented in processed header, one is updated.

## Caveats

Any distortions, including atmospheric refraction, are not implemented yet. Gnomonic projection is available only.

## Examples

### Sources Of Astrometric Catalogues

Virtual Observatory (VO) is intended as the main source of catalogues. The following example uses cone search capability of VO to list part of UCAC5 catalogue

    munipack cone -c UCAC5 -o 0716cat.fits -r 0.1 -- 110.25 71.34

UCAC5 is the recommended astrometric catalogue (default). We must provide coordinates of centre of frame (use coordinates of assumed object) and the cone radius (else a catalogue default will be used). Note parameter -s (sort by a column). The sorting requires knowledge of catalogue structure but strongly affects speed and success rate of matching.

## Manual Calibration

Manual calibration is designed with its properties:

- The proper calibration is known.
- No catalogue and objects detection on images is required.

To save a calibration to FITS header, find the parameters by hand and adjust the example

    $ munipack astrometry -m manual -p GNOMONIC --rcen=110.471 --dcen=71.351
                --scale=5.64e-04 --angle=0.0 0716_1R.fits

This is an example for blazar 0716+71 which observation is in FITS file 0716_1R.fits included to munipack-blazar.tar.gz.

The calibration parameters are left untouched. There are are no limits and no any checks.

Parameters for manual calibration[a]
Parameter | Description | Units
--- | --- | ---
-p | Type of spherical projection |
--rcen | Right Ascension of centre of the projection αc (CRVAL1)[b] | degrees
--dcen | Declination of centre of the projection δc (CRVAL2)[b] | degrees
--xcen | Reference point on a chip xc (CRPIX1)[b] | pixels
--ycen | Reference point on a chip yc (CRPIX2)[b] | pixels
--scale | Scale of projection c | degrees/pixel
--angle | Angle of rotation around centre φ | degrees
--reflex | Reflected frame | degrees
`file` | a file to calibrate[c] |

[a] The manual calibration is invoked when `-m manual` is presented.

[b] Twines of parameters `--xcen, --ycen` and `--rcen, --dcen` must be specified together.

[c] This manual calibration works only on a single file. Others types of calibrations on a list of files.

## Matching And Sequence Calibration

Astrometric calibration is designed with its properties:

- High precision as possible.
- Minimum of manually provided parameters

### Prerequisites

Astrometry calibration requires detected stars (see find), aperture photometry (see aphot) and an astrometry catalogue (cone search).

At the start, astrometry calibration itself can be done, a star table (list) of objects on an image must be prepared.

The object detection (as a side effect is the aperture photometry) is relative straightforward (detected objects are stored to another HDU with label FIND):

    $ munipack find -f 2 -t 5  0716_1R.fits
    $ munipack aphot 0716_1R.fits

A catalogue with reference stars can be got with help of Virtual Observatory:

    $ munipack -o 0716_cat.fits -r 0.2 cone -- 110.25 71.34

Selected astrometric stars in radius 0.2° around centre α = 110.25° and δ = 71.34° are saved to the FITS table 0716_cat.fits.

Note selection of catalogue UCAC5. The objects stored to the output file are sorted by magnitude designed as 'f.mag'. You must known catalogue structure before use of -s (simply get catalogue without -s option, look for structure and than use -s with right parameter). Sorting importantly increase probability of successful matching.

### Invoking of Matching

In case of matching, when your are a lucky user, following command would give you the excellent job:

    $ munipack astrometry -c 0716_cat.fits  0716_1R.fits

### Invoking of Sequence

      $ munipack astrometry -m SEQUENCE \
         --seq1 5,6,9,16,17,18,19,21,23,22,24,26,27,29,28,30,32 \
         --seq2 1,2,3,5,4,8,11,13,7,10,6,12,9,18,14,19,17 \
         -c 0716_cat.fits  0716_1R.fits

Parameters for astrometric calibration
Parameter | Description
--- | ---
-p | Spherical projection
-c | Reference astrometry catalogue[‡]
-r | Reference already calibrated frame[‡]
-R | Reference frame for relative astrometry (no projection)[‡]
--col-ra | Label of Right Ascension column
--col-dec | Label of Declination column
--col-pm-ra | Label of proper motion of Right Ascension column
--col-pm-dec | Label of proper motion of Declination column
--minmatch | match sequence minimal length[†]
--maxmatch | match sequence length[†]
`file` | a file to calibrate

[‡] Parameters -c, -r and -R are exclusive mutual.

[†] Parameters --minmatch and --maxmatch affects both speed (greater is slower) and chance of matching (lower is worse). The recommended values for --minmatch are 5 - 10 (default is 5) and --maxmatch 20 - 200 (default 33).

## Tips For Usage

### Successful Matching

Matching needs at least `--minmatch` common stars on frame and catalogue as selected `--maxmatch`. When matching is failed, check all centre, radius and proper reference catalogue.

As the best diagnostics tool is the astrometry in xmunipack (Tools->Astrometry).

### Fine Tune Of Calibration

The matching of the reference catalogue with detected stars is extremely complicated procedure. Therefore, there are tun-able parameters for both matching and fitting algorithms. In doubts, check ones:

- The sorting of the table with astrometric stars. Stars would be sorted from the most brighter to faintness ones (parameter -s of the cone search, tables of detected objects are sorted by default)
- The search region is overlapping of the field of view of matched pictures.
- Try increase number of stars used for matching (--maxmatch) and a match sequence length (--minmatch). Large values of both parameters slow-downs matching.

### Tracing

It is always possible to get detailed log of processing invoking of `--verbose` parameter. The usual log will like

    $ munipack astrometry --verbose 0716_006V.fits
    Debug: Launching `astrometry' ...
    Debug: VERBOSE = T
    Debug: COL_RA = 'RAJ2000'
    Debug: COL_DEC = 'DEJ2000'
    Debug: COL_PMRA = 'pmRA'
    Debug: COL_PMDEC = 'pmDE'
    Debug: COL_MAG = 'f.mag'
    Debug: CAT = 'cone.fits'
    Debug: FILE = '0716_006V.fits' '0716_006V.fits~' ''
     Selecting catalogue stars in rank:           1          33
     Matching... #: {seq1} -> {seq2} | scale,r: sq.(angle, scale, flux) < Xi2(0.95)
     Astrometry calibration of `0716_006V.fits'.
    17: 5 6 9 16 17 18 19 21 23 22 24 26 27 29 28 30 32 ->  1 2 3 5 6 4 13 10 7 11 12 9 8 18 14 21 16 | 1767.5  4.53:   1.36  .669E-001  15.7 < 26.0
    17: 28 29 5 6 9 16 17 18 19 21 23 22 24 26 27 30 32 ->  14 18 1 2 3 5 6 4 13 10 7 11 12 9 8 21 16 | 1767.5  4.53:   .553  .710E-001  15.7 < 26.0
     === Parameters estimation ===
    # estim init scale [pix/deg]:     1767.6       0.1
    # estim init reflexion:    1.
    # estim init angle [deg]:    0.549   0.011
    # estim init offset [deg]:      0.01313     0.10040     0.00001     0.00001
     === Absolute deviations fitting ===
    # ifault   mad     acen         dcen       offset[pix]    s[pix/deg] rot[deg]
    Debug: MuniProcess elapsed time: 00h 00m 08.945s
    Debug: MuniProcess::OnFinish: 24466 0.
     1 2  3.16E-05  110.50989   71.29578    24.        92.        1767.4    0.6
     2 2  3.17E-05  110.46739   71.34808   0.61E-03  -0.11E-03    1767.4    0.5
     3 0  3.13E-05  110.46739   71.34808  -0.90E-02  -0.11E-02    1767.6    0.5
     4 0  3.13E-05  110.46740   71.34807  -0.18E-05  -0.83E-05    1767.6    0.5
     5 0  3.13E-05  110.46740   71.34807    0.0        0.0        1767.6    0.5
    # absfit sign test (total, positive ra,dec):      17      9      8
    # absfit final:   31.32E-06    1.768E+03     0.5  110.46740   71.34807  1.0
    # astrofit   mad=.313E-004 deg  .113 arcsec
    # astrofit stars to fit: 43
     === Robust fitting ===
    Likelihood solution: status=0 (evaluations=2383), log L =   -819.
    # info    s       acen         dcen        offset[pix]       [pix/deg] rot[deg]
     0 0  3.98E-05  110.46740   71.34807   0.267E-01   0.927E-02    1767.4    0.5
     1 2  3.98E-05  110.46740   71.34807   0.253E-01   0.704E-02    1767.4    0.5
     2 2  3.97E-05  110.46736   71.34808  -0.355E-05  -0.311E-05    1767.4    0.5
     3 2  3.97E-05  110.46736   71.34808    0.00        0.00        1767.4    0.5
    # Hessian at minimum:
    #     36.000         0.0000        -311.66       -0.35596
    #     0.0000         31.000         572.02        0.43994
    #    -311.66         572.02        0.10717E+07     90.344
    #   -0.35596        0.43994         90.344        0.29904
    # Covariance matrix (no regularisation):
    #    0.28150E-01   -0.56872E-03    0.57410E-05    0.32610E-01
    #   -0.56872E-03    0.33159E-01   -0.14053E-04   -0.45214E-01
    #    0.57410E-05   -0.14053E-04    0.96456E-06   -0.26390E-03
    #    0.32610E-01   -0.45214E-01   -0.26390E-03     3.5291
    # Correlation matrix:
    #    1.000   -0.019    0.035    0.103
    #   -0.019    1.000   -0.079   -0.132
    #    0.035   -0.079    1.000   -0.143
    #    0.103   -0.132   -0.143    1.000
    # solution:      0.000E+00    0.000E+00    5.658E-04    8.862E-03    3.975E-05
    # deviations:     5.65E-06     6.13E-06     3.31E-08     6.33E-05    -1.00E+00
    # s0,rms:   4.42E-08  3.41E-05 [deg]    .123 [arcsec]
    # s:   3.97E-05 [deg]    .143 [arcsec]
    # sign test (total, RA+, Dec+):      43/21.5   17+-2.1   21+-2.3
    ....

## See Also

Astrometry Overview, WCS Header