Column index for optional weights. If specified, this column should contain a valid non\-negative real number which is used as a weight during the least\-squares fit.
.TP
\fB\-\-weight\fR [magnitude],[power=]
These directives specify the weights which are used during the fit of the functions or transformations. For example, in practice it is useful in the following situation. We try to match star lists, then the fainter stars are believed to have higher astrometrical errors, therefore they should have smaller influence in the fit. We can take the weights from a given colum, specified by the index after \fB\-\-col\-weight\fR (see above). The weights can be derived from stellar magnitudes, if so, specify "magnitude" to convert the read values in magnitude to flux. The real weights then is the "power"th power of the flux. The default value of the "power" is 1, however, for the maximum\-likelihood estimation of an assumed Gaussian distribution, the weights should be the second power of the fluxes.
.TP
\fB\-ot\fR, \fB\-\-output\-transformation\fR
Name of the output transformation file containing the result of the fit (see above).
.SS "General options for transformation or function evaluation:"
.TP
\fB\-\-input\-transformation\fR
Name of the input transformation file containing the desired transformation (see above).
.TP
\fB\-\-reverse\fR, \fB\-\-inverse\fR
Perform inverse transformation. This is a valid option only if the dimension of the fitted function is the same as the dimension of the independent variables (namely, 2, because in the actual implementation the latter can only be 2).
.TP
\fB\-\-col\-xy\fR ,
Column indices for the independent values. In the current implementation, `grtrans` can only fit polynomial functions of exactly 2 independent variables. Lines where these columns do not contain valid real numbers are excluded.
.TP
\fB\-\-col\-out\fR <>[,<>[,<>]...]
Column indices for the evaluated output variables. The number of indices listed here should be the same as the number of independent functions stored in the input transformation file.
.SS "General options for transformation composition:"
.TP
\fB\-\-input\-transformation\fR
Name of the input transformation file.
.TP
\fB\-\-scale\fR
Scale factor.
.TP
\fB\-\-offset\fR ,
Shift. The affine transformation with which the input transformation is composed is going to be: x'=dx+s*x, y'=dy+s*y.
.TP
\fB\-\-output\-transformation\fR
Name of the output transformation file containing the result of the composition.
.SS "Options for spherical projection and deprojection:"
.TP
\fB\-\-wcs\fR [sin|arc|tan],ra=,dec=,[degrees|radians|scale=
This set of directives specify the common parameters of the spherical projection or deprojection. The "sin", "arc" and "tan" directives set the type of projection to orthographic, arc and gnomonic, respectively. The values after "ra" and "dec" ( and ) specify the center of the projection (right ascension and declination, respectively, in degrees). The "degrees", "radians" or the "scale=" directives specify the scaling of the output. The directive "degrees" is equivalent to set "scale=57.29577951308232087721" (180 over \ePi), this is the default. The directive "radians" is equivalent to set "scale=1".
.TP
\fB\-\-col\-radec\fR ,
Column indices for RA and DEC values. This option implies projection.
.TP
\fB\-\-col\-pixel\fR ,
Column indices for X and Y projected values. This option implies deprojection.
.TP
\fB\-\-col\-out\fR <>,<>
Column indices for the output values (which are X and Y for projection and RA, DEC for deprojection).
.SS "Options for fitting WCS information:"
.TP
\fB\-\-wcs\fR [sin|arc|tan],ra=,dec=,order=
This set of directives specify the common parameters of WCS fitting. The projection can be orthographic, arc or gnomonic (however, there are dosens of projections implemented in the FITS WCS system, but for practical purposes, such projections seem to be more than enough). The center of the fit is set by "ra" and "dec" (RA and DEC, in degrees). The distortion order is specified by order. Note that the RA and DEC values specified here can only be an assumed values.
.TP
\fB\-\-col\-ref\fR <>,<>
Column indices for the Ra and Dec values.
.TP
\fB\-\-col\-fit\fR <>,<>
Column indices for the pixel values.
.PP
Note that in this case, the set of the appropriate FITS keyword=value pairs are written directly stdout, not in the file specified by the options \fB\-\-output\fR or \fB\-\-output\-transformation\fR.
.SH EXAMPLES
Here is an example for a complete astrometry problem which demonstrates the proper usage of the programs grmatch and grtrans. Let us assume that we have 1/ a reference star catalogue, named "catalog.dat", a file with four columns: the first is the identifier of the star, the second and third are the celestial coordinates (RA and DEC, in degrees), and the last is the magnitude of the stars; 2/ an astronomical image, named "img.fits" (not crucial for the astrometry itself, it is required only by the demonstration of the export of FITS WCS headers); and 3/ a list of decected stars (from "img.fits"), named "img.star", a file with three columns: the first two are the pixel coordinates and the third is an estimation of the flux (in ADUs, not in magnitudes).
.PP
Let us also denote the celestial coordinates of the center of the image by R and D, the RA and DEC values, in degrees and, for example let R=220 and D=25, a field in the Bootes. Let us also assume that the size of our field (both the catalog and the list of the deceted stars) is 3 degrees and there are approximately 4000\-4000 stars both in the reference catalog and in the list of the detected stars. Because we have such a large amount of stars, one can use only a fraction of them for triangulation.
.PP
The first step is to make a projection from the sky, centered around the center of our image:
.IP
grtrans \-\-input catalog.dat \-\-wcs tan,degrees,ra=220,dec=25 \-\-col\-radec 2,3 \-\-col\-out 5,6 \-\-output img.proj
.PP
The second step is the point matching:
.IP
grmatch \-\-reference img.proj \-\-col\-ref 5,6 \-\-col\-ref\-ordering \-4 \-\-input img.star \-\-col\-inp 1,2 \-\-col\-inp\-ordering +3 \-\-match\-points \-\-order 4 \-\-triangulation auto,unitarity=0.01,maxnumber=1000,conformable \-\-max\-distance 1 \-\-weight reference,column=4,magnitude,power=2 \-\-comment \-\-output\-transformation img.trans
.PP
This grmach invocation matches the stars from projected reference catalog, "img.proj " and the detected stars. The "\-\-order 4" specifies a fourth\-order polynomial fit, which is, in practice, good for a field with the size of 3 degrees. The directives after "\-\-weight" makes the magnitudes taken from the reference file to be used as a weight for fitting. This invocation yields one new file, "img.trans" which stores the fitted 4th\-order polynomial transformation which transforms the projected coordinates to the system of the image.
.PP
The next step is the astrometrical transformation, we create a "local" catalog, which is the original catalog extended with the proper X and Y plate coordinates:
.IP
grtrans \-\-input img.proj \-\-col\-xy 5,6 \-\-input\-transformation img.trans \-\-col\-out 7,8 \-\-output img.cat
.PP
This invocation yields an other new file, "img.cat" which has 8 columns. The first six columns are the same as it was in "img.proj" (identifier, RA, DEC, magnitude and projected X, Y coordinates), the last two colums are the fitted plate coordinates. Then, the proper WCS headers can be determined by the following call:
.IP
grtrans \-\-input img.cat \-\-col\-ref 2,3 \-\-col\-fit 7,8 \-\-wcs tan,order=4,ra=220,dec=25 >img.wcs
.PP
The newly created file, img.wcs contains the FITS "keyword"="value" pairs, which can be exported to "img.fits" to have a standard header extended by the WCS information. For exporting, the program fiheader(1) can be used:
.IP
fiheader img.fits \-\-rewrite \-\-update "$(cat img.wcs)"
.PP
Note that the last two grtrans calls can be replaced by a single pipeline, when the file img.cat is not created:
.IP
grtrans \-\-input img.proj \-\-col\-xy 5,6 \-\-input\-transformation img.trans \-\-col\-out 7,8 \-\-output \- | grtrans \-\-input \- \-\-col\-ref 2,3 \-\-col\-fit 7,8 \-\-wcs tan,order=4,ra=220,dec=25 >img.wcs
.SH "REPORTING BUGS"
Report bugs to , see also http://fitsh.net/.
.SH COPYRIGHT
Copyright \(co 1996, 2002, 2004\-2008, 2010\-2015; Pal, Andras