grtrans - transforming coordinate lists or fitting such transformations

       Copyright © 1996, 2002, 2004-2008, 2010-2016, 2018-2020; Pal, Andras <apal@szofi.net>

grtrans 0.9.4 (2021.01.24)                        January 2021                                        GRTRANS(1)

       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.

       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

       grtrans - transforming coordinate lists or fitting such transformations

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

   Optionsforinput/outputspecification:
       <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.

   Generaloptionsforfittingpolynomialcoefficients:--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).

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

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

   Optionsforsphericalprojectionanddeprojection:--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).

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

       Report bugs to <apal@szofi.net>, see also https://fitsh.net/.

grtransh [options] <input> [-o<output>]