GRTRANS(1)

📦 version 0.9.4, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

🌸 NAME 🌸

grtrans — transforming coordinate lists or fitting such transformations 💅 (this is the GRTRANS(1) page, User Commands, bestie, you're in the right place)

💫 SYNOPSIS 💫

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

🦋 DESCRIPTION 🦋

okay so the whole main character energy of grtrans is two things: transforming coordinate lists and fitting transformations to input data. that's the vibe. and the transformation it does can be any one of these methods:

  1. Evaluate polynomial functions (with arbitrary order) of two independent values. ✨
  2. Two dimensional spherical projection — aka converting to RA/DEC or longitude/latitude values to projected coordinates on a given tangent plane. 🌈
  3. Two dimensional spherical de-projection — the reverse, 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. 💫

and it's not just a transformer, it's also a fitter, periodt. 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. the basics, bestie. 💖
  • --long-help, --help-long — gives a detailed list of command line options. the full lore. 📜
  • --wiki-help, --help-wiki, --mediawiki-help, --help-mediawiki — gives a detailed list of command line options in Mediawiki format. wiki girlies rise 🫶
  • --version, --version-short, --short-version — give some version information about the program. who am i? 💅
  • -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 (and yeah, specifying some input is mandatory, no input no party 🙈).
  • -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. iconic behavior honestly. 🎀

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. 💀 so like, watch where that's going bestie

💖 EXAMPLES 💖

okay bestie, this is the part where it all comes together — a full astrometry glow-up using grmatch and grtrans together. Let's set the scene ✨

So picture this: we've got

  • a reference star catalogue called catalog.dat, with four columns. Col 1 is the star's identifier, cols 2 and 3 are the celestial coordinates (RA and DEC, in degrees), and the last one is the star's magnitude 🌟
  • an astronomical image called img.fits — and ngl, this one is not crucial for the astrometry itself, it only matters for the demo of exporting FITS WCS headers 🖼️
  • and a list of detected stars (from img.fits) called img.star, with three columns: first two are pixel coordinates, third is an estimation of the flux (in ADUs, not magnitudes, okay? not magnitudes 💅)

Now let's also call the celestial coordinates of the center of the image R and D — the RA and DEC values, in degrees. For example, let R=220 and D=25, a field in the Bootes 🦋 And let's say the size of our field (both the catalog and the list of the detected stars) is 3 degrees, with approximately 4000-4000 stars in the reference catalog and in the detected-stars list. Since we've got such a big amount of stars, you can legitimately use just a fraction of them for triangulation. slay, less work for you 💅

Step 1 — project from the sky 🌀

First up: 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

Step 2 — point matching 🔗

Then we do 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

So this grmatch invocation matches the stars from the projected reference catalog, img.proj, against 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 make the magnitudes taken from the reference file get used as a weight for the fitting. And this invocation yields one new file, img.trans, which stores the fitted 4th-order polynomial transformation that transforms the projected coordinates to the system of the image. periodt ✨

Step 3 — the astrometrical transformation 🌈

Next: 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 another 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), and the last two columns are the fitted plate coordinates 🫶

Then the proper WCS headers can be determined by this 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)"
heads up bestie — 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 🐛

Found a bug? no cap, please report it to <apal@szofi.net>. See also https://fitsh.net/ — iykyk 💜

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

and that's a wrap, bestie 🎀 this whole glow-up is from grtrans 0.9.4, dated 2021.01.24, with the page itself going out in January 2021 — go project some stars, you absolute icon 💅✨

📦 where this page comes from