Warp will warp an input image into a new pixel grid by pixel mixing (see Resampling). Without any options, Warp will remove any non-linear distortions from the image and align the output pixel coordinates to its WCS coordinates. Any homographic warp (for example, scaling, rotation, translation, projection, see Linear warping basics) can also be done by calling the relevant option explicitly. The general template for invoking Warp is:
$ astwarp [OPTIONS...] InputImage
One line examples:
## Align image with celestial coordinates and remove any distortion
$ astwarp image.fits
## Align four exposures to same pixel grid and stack them with
## Arithmetic program's sigma-clipped mean operator (out of many
## stacking operators, see Arithmetic's documentation).
$ grid="--center=1.234,5.678 --width=1001,1001 --widthinpix --cdelt=0.2/3600"
$ astwarp a.fits $grid --output=A.fits
$ astwarp b.fits $grid --output=B.fits
$ astwarp c.fits $grid --output=C.fits
$ astwarp d.fits $grid --output=D.fits
$ astarithmetic A.fits B.fits C.fits D.fits 4 5 0.2 sigclip-mean \
-g1 --output=stack.fits
## Warp a previously created mock image to the same pixel grid as the
## real image (including any distortions).
$ astwarp mock.fits --gridfile=real.fits
## Rotate and then scale input image:
$ astwarp --rotate=37.92 --scale=0.8 image.fits
## Scale, then translate the input image:
$ astwarp --scale 8/3 --translate 2.1 image.fits
## Directly input a custom warping matrix (using fraction):
$ astwarp --matrix=1/5,0,4/10,0,1/5,4/10,0,0,1 image.fits
## Directly input a custom warping matrix, with final numbers:
$ astwarp --matrix="0.7071,-0.7071, 0.7071,0.7071" image.fits
If any processing is to be done, Warp needs to be given a 2D FITS image. As in all Gnuastro programs, when an output is not explicitly set with the --output option, the output filename will be set automatically based on the operation, see Automatic output. For the full list of general options to all Gnuastro programs (including Warp), please see Common options.
Warp uses pixel mixing to derive the pixel values of the output image, see Resampling. To be the most accurate, the input image will be read as a 64-bit double precision floating point dataset and all internal processing is done in this format. Upon writing, by default it will be converted to 32-bit single precision floating point type (actual observational data rarely have such precision!). In case you want a different output type, you can use the --type option that is common to several Gnuastro programs. For example, if your input is a mock image without noise, and you want to preserve the 64-bit precision, use (with --type=float64. Just note that the file size will also be double! For more on the precision of various types, see Numeric data types.
By default (if no linear operation is requested), Warp will align the pixel grid of the input image to the WCS coordinates it contains. This operation and the the options that govern it are described in Align pixels with WCS considering distortions. You can Warp an input image to the same pixel grid as a reference FITS file using the --wcsfile option. In this case, the output image will take all the information needed from the reference WCS file and HDU/extension specified with --wcshdu, thus it will discard any other resampling options given.
If you need any custom linear warping (independent of the WCS, see Linear warping basics), you need to call the respective operation manually. These are described in Linear warps to be called explicitly. Please note that you may not use both linear and non-linear modes simultaneously. For example, you cannot scale or rotate the image while removing its non-linear distortions at the same time.
The following options are shared between both modes:
Specify the first header keyword number (line) that should be used to read the WCS information, see the full explanation in Invoking Crop.
Specify the last header keyword number (line) that should be used to read the WCS information, see the full explanation in Invoking Crop.
Depending on the warp, the output pixels that cover pixels on the edge of the input image, or blank pixels in the input image, are not going to be fully covered by input data.
With this option, you can specify the acceptable covered fraction of such pixels (any value between 0 and 1).
If you only want output pixels that are fully covered by the input image area (and are not blank), then you can set --coveredfrac=1 (which is the default!).
Alternatively, a value of 0 will keep output pixels that are even infinitesimally covered by the input.
As a result, with --coveredfrac=0, the sum of the pixels in the input and output images will be exactly the same.
GNU Astronomy Utilities 0.23 manual, July 2024.