Munipack's logo


An astronomical image processing software



An astrometry calibration of FITS frames.


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


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

Astrometry is naturally separated on two parts:


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
sparse field, < 1 m telescopedefaults
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]'


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:

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


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.


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]
  • 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 of rotation [deg], clockwise positive
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.
Finish at first success match when --minmatch is reached. Alias for --luckymatch 0
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.
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.
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).


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

See Common options for input/output filenames.

Following combinations of mode and options are possible
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.


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


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:

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]
-pType of spherical projection
--rcenRight Ascension of centre of the projection αc (CRVAL1)[b]degrees
--dcenDeclination of centre of the projection δc (CRVAL2)[b]degrees
--xcenReference point on a chip xc (CRPIX1)[b]pixels
--ycenReference point on a chip yc (CRPIX2)[b]pixels
--scaleScale of projection cdegrees/pixel
--angleAngle of rotation around centre φdegrees
--reflexReflected framedegrees
filea 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:


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
-pSpherical projection
-cReference astrometry catalogue[‡]
-rReference already calibrated frame[‡]
-RReference frame for relative astrometry (no projection)[‡]
--col-raLabel of Right Ascension column
--col-decLabel of Declination column
--col-pm-raLabel of proper motion of Right Ascension column
--col-pm-decLabel of proper motion of Declination column
--minmatchmatch sequence minimal length[†]
--maxmatchmatch sequence length[†]
filea 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:


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