Provided by: fitsh_0.9.4-1_amd64 
NAME
grtrans - transforming coordinate lists or fitting such transformations
SYNOPSIS
grtransh [options] <input> [-o <output>]
DESCRIPTION
The main purpose of the program `grtrans` is to transform coordinate lists and fit
transfomrations to input data. The transformation can be one of the following methods. 1.
Evaluate polynomial functions (with arbitrary order)of two independent values. 2. Two
dimensional spherical projection (converting to RA/DEC or longitude/latitude values to
projected coordinates on a given tangent plane. 3. Two dimensional spherical de-projection
(converting tangent planar coordinates to RA/DEC or longitude/latitude values). 4. Compose
arbitrary polynomial functions of two independent values with arbitrary two-dimensional
affine (or linear) transformations. The program also can be used to fit functions,
namely fit the coefficients of arbitrary-order polynomial functions of two independent
values or fit WCS distortion parameters.
OPTIONS
General administrative options:
-h, --help
Give general summary about the command line options.
--long-help, --help-long
Gives a detailed list of command line options.
--wiki-help, --help-wiki, --mediawiki-help, --help-mediawiki
Gives a detailed list of command line options in Mediawiki format.
--version, --version-short, --short-version
Give some version information about the program.
-C, --comment
Comment the output.
Options for input/output specification:
<inputfile>, -i <inputile>, --input <inputfile>
Name of the input file. If this switch is omitted, the input is read from stdin
(specifying some input is mandatory).
-o <output>, --output <output>, --output-matched <output>
Name of the output file, if the program was used for transforming coordinate
lists.
-T, --input-transformation <output-transformation-file>
Name of the input transformation file (see also the notes below).
--output-transformation <output-transformation-file>
Name of the output file containing the fitted geometrical transformation, in
human-readable format (see also the notes below).
In all of the above input/output file specifications, the replacement of the file name
by "-" (a single minus sign) forces the reading from stdin or writing to stdout. Note
that all parts of the any line after "#" (hashmark) are treated as a comment, therefore
ignored. Note that there is no explicit switch for distinguishing between the fitting
and the evaluating purposes of the program. If --input-transformation has been specified,
the program implies that the user wants to evaluate a function described by this
existing transformation file. On the other hand, if --output-transformation has been
specified, the program fits the parameters of the function and stores the resulted
transformation file as it specified by the argument of this option. In other words, if
no WCS or spherical (de)projection declared by the directives of --wcs, one of these two
switches should be given in the command line.
General options for fitting polynomial coefficients:
--col-xy <x>,<y>
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.
--col-fit <>[,<>[,<>]...]
Column indices for the dependent values. In the current implementation, grtrans
can only fit 2 dimensional polynomial functions to arbitrary dimensional data. The
dimension of the fitted data is specified indirectly, by the number of column
indices specified after this switch.
-a <order>, --order <order>
Order of the fitted polynomial function. It can be any positive integer.
-n <N>, --iterations <N>; -r <S>, --rejection-level <S>
These switches specify the total number of rejection iterations of outlyer points
and the rejection level in sigma units. By default, no rejection is applied,
therefore all valid lines are used.
--col-weight <w>
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.
--weight [magnitude],[power=<P>]
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 --col-weight (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.
-ot, --output-transformation <output-transformation-file>
Name of the output transformation file containing the result of the fit (see
above).
General options for transformation or function evaluation:
--input-transformation <input-transformation-file>
Name of the input transformation file containing the desired transformation
(see above).
--reverse, --inverse
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).
--col-xy <x>,<y>
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.
--col-out <>[,<>[,<>]...]
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.
General options for transformation composition:
--input-transformation <input-transformation-file>
Name of the input transformation file.
--scale <s>
Scale factor.
--offset <dx>,<dy>
Shift. The affine transformation with which the input transformation is composed is
going to be: x'=dx+s*x, y'=dy+s*y.
--output-transformation <output-transformation-file>
Name of the output transformation file containing the result of the composition.
Options for spherical projection and deprojection:
--proj, --project
[sin|arc|tan],ra=<R>,dec=<D>,[roll=<F>],[max=<max_distance>],[qr=<R>,qi=<I>,qj=<J>,qk=<K>],[degrees|radians|scale=<S>
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" (<R> and <D>) specify the center of the projection (right
ascension and declination, respectively, in degrees). The optional parameter <F>
is for the roll angle (in degrees). The "degrees", "radians" or the "scale=<S>"
directives specify the scaling of the output. The directive "degrees" is
equivalent to set "scale=57.29577951308232087721" (180 over \Pi), this is the
default. The directive "radians" is equivalent to set "scale=1". Alternatively to
the right ascension, declination and roll parameterization, one can use
quaternion-based pointing here by specifying qr, qi, qj, qk for the real, and the
three imaginary components, respectively.By default, this projection tries to
compute the projected coordinates for all of the positions presented in the input
list. However, it might yield unexpected results in certain cases (e.g. an input
list on a nearly full sphere and orthographic projection). One can use the
"max=<max_distance>" parameter to filter objects beyond this maximum distance.
--col-radec <r>,<d>
Column indices for RA and DEC values. This option implies projection.
--col-pixel <x>,<y>
Column indices for X and Y projected values. This option implies deprojection.
--col-out <>,<>
Column indices for the output values (which are X and Y for projection and RA, DEC
for deprojection).
Options for fitting WCS information:
--wcs [sin|arc|tan],ra=<R>,dec=<D>,order=<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,
however, the larger the optical distortions are, the better to have RA and DEC
values close to the optical axis.
--col-ref <>,<>
Column indices for the RA and DEC values.
--col-fit <>,<>
Column indices for the pixel values.
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 --output or
--output-transformation.
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).
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.
The first step is to make a projection from the sky, centered around the center of our
image:
grtrans --input catalog.dat --proj tan,degrees,ra=220,dec=25 --col-radec 2,3
--col-out 5,6 --output img.proj
The second step is the point matching:
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
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.
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:
grtrans --input img.proj --col-xy 5,6 --input-transformation img.trans --col-out
7,8 --output img.cat
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:
grtrans --input img.cat --col-ref 2,3 --col-fit 7,8 --wcs tan,order=4,ra=220,dec=25
>img.wcs
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:
fiheader img.fits --rewrite --update "$(cat img.wcs)"
Note that the last two grtrans calls can be replaced by a single pipeline, when the file
img.cat is not created:
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
REPORTING BUGS
Report bugs to <apal@szofi.net>, see also https://fitsh.net/.
COPYRIGHT
Copyright © 1996, 2002, 2004-2008, 2010-2016, 2018-2020; Pal, Andras <apal@szofi.net>