Provided by: fitsh_0.9.4-1_amd64 bug

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>