FITRANS(1)

💫 fitrans — the spatial-transformation glow-up page 💫

okay bestie, welcome to FITRANS(1), part of the User Commands crew 🎀 this is the manual for fitrans, and no cap, it's the tool you want when your image needs to be moved, squished, stretched, smoothed, sliced or exploded into a million little stamps. yes, exploded. we'll get there. 🌸

---

✨ NAME ✨

fitrans — performing spatial transformations on the input image 🦋

---

🌈 SYNOPSIS 🌈

fitrans [transformation and options] <input> [-o|--output <output>]

---

💖 DESCRIPTION 💖

So the main purpose of this program, like its whole ~main character energy~, is to perform specific or generic geometric transformations on the input image. that's it. that's the vibe. you feed it an image, you tell it how to warp it, it hands you back a warped image. periodt. 👑

---

🎀 OPTIONS 🎀

💅 General options:

• -h, --help — gives you a general summary about the command line options. the lil' quickie version. ✨
• --long-help, --help-long — gives a detailed list of command line options. the full tea. ☕
• --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 — gives some version information about the program.
• -i, --input <image file> — name of the input FITS image file. your source material 💖
• -o, --output <image file> — name of the output FITS image file. where the glow-up lands.
• -b, --bitpix <bitpix> — standard FITS output bitpix value.
• -D, --data <spec> — output pixel data format specification.

---

🦋 Spatial transformations:

• -T, --input-transformation <transformation file> — name of the file which contains the transformation description. such a file can be created e.g. by the programs grtrans or grmatch. this file contains basically the same set of <keyword> = <value> pairs as it is used after the -t|--transformation option (see there). 👀
• -t, --transformation <transformation> — comma-separated list of parameters for the spatial transformation, see the section "Parameters for spatial transformations" below. 🧚
• -e, --shift <dx>,<dy> — imply a transformation that shifts the image by <dx>,<dy>.
• --reverse, --inverse — apply the inverse transformation to the image rather than the original one. plot twist 💀
• -m — simple linear interpolation between pixels, with no exact flux conservation (just a multiplication by the Jacobian of the transformation).
• -l — linear interpolation between the pixels involving exact flux conservation by integrating on the image surface.
• -c — bicubic spline interpolation between pixels, with no exact flux conservation (just a multiplication by the Jacobian of the transformation).
• -k — interpolation by integrationg the flux on a biquadratic interpolation surface, yielding exact flux conservation.
• -s, --size <sx>,<sy> — the size of the output image if it should differ from the original image size.
• -f, --offset <x>,<y> — zero-point coordinate of the output image in the input image.

---

💜 Parameters for spatial transformations:

• type=<type> — type of the transformation. in the actual implementation, the only supported type for a transformation is "polynomial". one type only, she's exclusive 💅
• order=<order> — polynomial order for the transformation.
• dxfit=<coefficients> — comma-separated list of the polynomial coefficients for the X coordinate. the number of coefficients must be 1, 3, 6, ... for the orders 0, 1, 2, ... respectively. math said triangle numbers only, bestie 🔺
• dyfit=<coefficients> — comma-separated list of the polynomial coefficients for the Y coordinate.

---

🌸 Other simple spatial geometric transformations:

• -z, --zoom <factor>, --zoom-xy <x>,<y> — zoom the image by the given (integer) factor, involving a biquadratic subpixel-level interpolation and therefore exact flux conservation.
• -r, --shrink <factor>, --shrink-xy <x>,<y> — shrink the image by the given (integer) factor(s).
• -d, --median — use a median-based averaging during the shrinking operation.
• -v, --truncated-mean <Nr> — compute a truncated mean during the shrinking operation by rejecting the <Nr> number of lower and upper points. bye bye outliers 👋
• --optimistic-masking — imply some optimism during the shrinking operation: masked pixels are ignored during the averaging process and the final mask will be computed in a complement manner. manifesting good pixels ✨
• -g, --magnify <factor>, --magnify-xy <x>,<y> — same as zooming the image but there is no subpixel-level interpolation.

---

🍓 Large-scale image smoothing:

• -a, --smooth <parameters> — perform a smoothing on the image. the parameters of the smoothing are the following:
  • spline — do a spline interpolation smoothing.
  • polynomial — do a polynomial interpolation smoothing.
  • [xy]order=<order> — spatial order of the smoothing function. the order in the X and Y coordinates can be set independently, by setting "xorder=..." or "yorder=...".
  • unity — scale the resulting smoothed image to have a mean of 1.
  • detrend — the resulting image will be the original image divided by the best fit smoothed surface.
  • [xy]hsize=<halfsize> — do a box filtering with the given halfsize.
  • mean — use the mean value of the pixels for the box filtering.
  • median — use the median value of the pixels for the box filtering.
  • iterations=<iterations> — number of iterations to reject outlier pixels from the box.
  • lower, upper, sigma=<sigma> — lower, upper or symmetric rejection level in the units of standard deviation.

---

🔥 Noise estimation:

• -n, --noise — derive an image which reflects the "noise level" of the image. ✨

---

🌈 Slicing or exploding data cube images:

• -y, --layer <layer> — layer (z-axis index) of the desired image slice.
• -x, --explode <basename> — explode the input image into individual planar (two dimensional) FITS image. the basename must contain at least one printf-like tag of %d, %i, %o, %x or %X that is replaced by the appropriate layer number index. 💥
• -y, --first-layer <n> — use the specified value for the first layer index. the subsequent layer indices are incremented normally. by default, the index of the first data cube layer is 0.

---

👑 Multiple stamp extraction:

• -c, --cut <basename> — extract stamps with a size defined by the -s|--size argument. the stamps are extracted on a grid, defined by the -p|--step and -w|--count arguments where the stamp grid offset is defined by the -f|--offset argument. the <basename> should contain two spefic printf-like elements of %x and %y which are replaced by the corresponding stamp indices in the X and Y directions. in order to have some sort of pretty-printing in the file names, the %x and %y parts may have the form of %.<N>x and %.<N>y. note that despite of the %x convention, both %x and %y are printed in decimal system. 🎀
• -w, --count <count_x>,<count_y> — number of stamps to be extracted in X and Y directions, respectively.
• -s, --size <sx>,<sy> — the size of the output image stamps.
• -p, --step <step_x>,<step_y> — step size between the stamps in the units of pixels and in the X and Y directions, respectively. note that if <step_x> is smaller than <sx> (or similarly, if <step_y> is smaller than <sy>), then the output stamps will overlap. this might also be intentional for various applications. overlapping stamps are a choice and honestly, valid 💅
• -f, --offset <x>,<y> — zero-point coordinate of the lower-left pixel of the lower-left output stamp (having an index of %x=0 and %y=0) in the frame of the input image.

---

😭 REPORTING BUGS 😭

report bugs to <apal@szofi.net>, see also https://fitsh.net/. bestie if it's broken, tell the devs, they wanna know 🫶

---

⭐ COPYRIGHT ⭐

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

---

and that's the whole page, bestie 💖 this was fitrans version 0.9.4 (2021.01.24), from January 2021, page FITRANS(1) — go transform something iconic, ily, bye 🎀✨