Previous: Resampling, Up: ImageWarp [Contents][Index]
The general template for invoking ImageWarp is:
$ astimgwarp [OPTIONS...] [matrix.txt] InputImage
One line examples:
$ astimgwarp matrix.txt image.fits $ astimgwarp --align rawimage.fits $ astimgwarp --scale 1.82 --translate 2.1 image.fits $ astimgwarp --rotate=37.92 --scale=0.8 image.fits $ astimgwarp --matrix=0.2,0,0.4,0,0.2,0.4,0,0,1 image.fits $ astimgwarp --matrix="0.7071,-0.7071 0.7071,0.7071" image.fits
ImageWarp can accept two arguments, one (an image) is mandatory if any processing is to be done. An optional argument is a plain text file, which must contain the warp/transform matrix, see Warping basics. When this text file is specified, then all options related to the matrix will be ignored (see below for the options). The general options to all Gnuastro programs (including ImageWarp) can be seen in Common options.
To be the most accurate the input image will be converted to double
precision floating points and all the processing will be done in this
format. By default, in the end, the output image will be converted
back to the input image data type. Note that if the input type was not
a floating point format, then the floating point output pixels are
going to be rounded to the nearest integer (using the round
function in the C programming language) which can lead to a loss of
data. This behavior can be disabled with the --doubletype
option. The input file and input warping matrix elements are stored in
the output’s header.
When using options, warps can be specified in a modular form, with options to specify each transformation (for example --rotate, or --scale), or directly as a matrix (with --matrix). If specified together, the latter (direct matrix) will take precedence and all the modular warpings will be ignored. Any number of modular warpings can be specified on the command-line and configuration files. If more than one modular warping is given, all will be merged to create one warping matrix. As described in Merging multiple warpings, matrix multiplication is not commutative, so the order of specifing the modular warpings on the command-line, and/or configuration files makes a difference (see Configuration file precedence). Below, the modular warpings are first listed (see Warping basics for the definition of each type of warping), then the other ImageWarp options.
Based on the FITS standard, integer values are assigned to the center of a pixel and the coordinate [1.0, 1.0] is the center of the bottom left (first) image pixel. So the point [0.0, 0.0] is half a pixel away (in each axis) from the bottom left vertice of the first pixel. The resampling that is done in ImageWarp (see Resampling) is dependent on this coordinate. So correction is done internally. With this resampling, the image must be warped relative to the bottom left vertice of the bottom left pixel and that point should lie at [0.0, 0.0]. So for a correct sampling, the warping center must first be translated by [0.5, 0.5], then the warp should be done and finally, a [-0.5, -0.5] translation should be specified. This correction is done internally in the following cases and can be disabled with the --nofitscorrect option.
Align the image and celestial (WCS) axes, such that the vertical image direction (when viewed in SAO ds9) corresponds to the declination and the horizontal axis is the inverse of the Right Ascension (RA). The inverse of the RA is chosen so the image can correspond to what you would actually see on the sky and is common in most survey images. Align is internally treated just like a rotation (--rotation), but uses the input image’s WCS to find the rotation angle.
(=FLT) Rotate the input image by the given angle in degrees. Note that commonly, the WCS structure of the image is set such that the RA is the inverse of the image horizontal axis which increases towards the right in the FITS standard and as viewed by SAO ds9. So the default center for rotation is on the right of the image. If you want to rotate about other points, you have to translate the warping center first (with --translate) then apply your rotation and then return the center back to the original position (with another call to --translate,z see Merging multiple warpings.
(=FLT[,FLT]) Scale the input image by the given factor. If only one value is given, then both image axises will be scaled with the given value. When two values are given, the first will be used to scale the first axis and the second will be used for the second axis. If you only need to scale one axis, use 1 for the axis you don’t need to scale.
(=FLT[,FLT]) Flip the image around the first, second or both axises. The first value specifies a flip on the first axis and the second on the second axis. The values of the option only matter if they are non-zero. If any of the values are zero, that axis is not flipped. So if you want to flip by the second axis only, use --flip=0,1 (which is equivalent to --flip=0,20 since it only matters if it is non-zero).
(=FLT[,FLT]) Apply a shear to the image along the image axises. If only one value is given, then both image axises will be sheared with the given value. When two values are given, the first will be used to shear the first axis and the second will be used for the second axis. If you only need to shear one axis, use 0 for the axis you don’t need.
(=FLT[,FLT]) Apply a translation to the image along the image axises. If only one value is given, then both image axises will be translated with the given value. When two values are given, the first will be used to translate along the first axis and the second will be used for the second axis. If you only need to translate one axis, use 0 for the axis you don’t need.
(=FLT[,FLT]) Apply a projection to the image along the image axises. If only one value is given, then the projection will be applied on both image axises with the given value. When two values are given, the first will be used for the first axis and the second will be used for the second axis. If you only need projection along one axis, use 0 for the axis you don’t need.
ImageWarp also provides the following options:
(=STR) The warp/transformation matrix. All the elements in this matrix must be separated by any number of space, tab or comma (,) characters. If you want to use the first two, then be sure to wrap the matrix within double quotation marks (") so they are not confused with other arguments on the command-line, see Options. This also applies to values in the configuration files, see Configuration file format.
The transformation matrix can be either 2 by 2 or 3 by 3 array. In the former case (if a 2 by 2 matrix is given), then it is converted to a 3 by 3 matrix with two translation terms added to correct for the FITS definition of position (see Warping basics, Merging multiple warpings, and the box above for more).
The determinant of the matrix has to be non-zero and it must not
contain any non-number values (for example infinities or NaNs). The
elements of the matrix have to be written row by row. So for the
general homography matrix of Warping basics, it should be called
with --matrix=a,b,c,d,e,f,g,h,1.
Do not correct for the FITS definition of the pixel center as described in the --matrix option.
(=INT) Specify the first header keyword number (line) that should be used to read the WCS information, see the full explanation in Invoking ImageCrop.
(=INT) Specify the last header keyword number (line) that should be used to read the WCS information, see the full explanation in Invoking ImageCrop.
Do not correct the WCS information of the input image and save it untouched
to the output image. By default the WCS (World Coordinate System)
information of the input image is going to be corrected in the output
image. WCSLIB will save the input WCS information in the PC
matrix84. To
correct the WCS, ImageWarp multiplies the PC matrix with the inverse
of the specified transformation matrix. Also the CRPIX point is
going to be changed to its correct place in the output image
coordinates. This behavior can be disabled with the
--nowcscorrection option.
Set output pixels which do not correspond to any input to zero. By default they are set to blank pixel values, see Blank pixels.
(=FLT) The maximum fractional area of blank pixels over the output pixel. If an output pixel is covered by blank pixels (see Blank pixels) for a larger fraction than the value to this option, the output pixel will be set to a blank pixel its self.
When the fraction is lower, the sum of non-blank pixel values over that pixel will be multiplied by the inverse of this fraction to correct for its flux and not cause discontinuities on the edges of blank regions. Note that even with this correction, discontinuities (very low non-blank values touching blank regions in the output image) might arise depending on the transformation and the blank pixels. So if there are blank pixels in the image, a good value to this option has to be found for that particular image and warp.
By default the output image is going to have the same type as the input image. If this option is called, the output will be in double precision floating point format irrespective of the input data type. When dealing with integer input formats, this option can be useful in checking the results.
Greisen E.W., Calabretta M.R. (2002) Representation of world coordinates in FITS. Astronomy and Astrophysics, 395, 1061-1075.
Previous: Resampling, Up: ImageWarp [Contents][Index]
GNU Astronomy Utilities 0.2.28-34fb manual, October 2016.