Name
warping - resample a frame according to a geometrical
transformation
Synopsis
warping [parameters] [options] <in> [out]
Description
warping is used to resample images according to a given
geometrical transformation. Supported transformations for
the moment are:
Integer
Integer transformations account for translations with
integer offsets and rotations of multiples of 90 degrees.
No resampling is performed in these cases, only pixel
shifts. Integer transformations are declared on the com-
mand-line exactly as linear transformations. The command
will decide to go to integer pixel shifts if it notices
that the input parameters are actually integer.
Linear
Linear transforms are covering translations, rotations,
scale changes (zoom). It is also possible to provide your
own expression of a linear transform as two linear polyno-
mials of x and y. Notice that the transform is then
direct: it transforms pixels from the original image into
pixels in the warped image.
Polynomial
General polynomial transformations are of any degree in x
and y. Provide on the command-line the degrees for x, y,
and the associated coefficient. It is possible to specify
only a x or y transformation. The other direction trans-
formation will then be Id. Notice that the transform is
then reversed (opposite of linear): it transforms pixels
in the warped image back into pixels in the original
image.
If you are trying to fit detector distorsions, it is usu-
ally enough to use low-order polynomials (up to 3rd
degree), because higher orders would introduce oscilla-
tions, producing undesirable rippling in the warped image.
See the adequate litterature about detector distorsions.
For distortion corrections, it is possible to use in
option the TFITS files produced by the ISAAC calibration
recipes is_spec_arc and is_spec_startrace and that contain
the distortion polynomials.
Resampling is done with kernel-based interpolations. Sev-
eral kernels are offered: sinc, square sinc, Lanczos2,
Hamming, Hann, and tanh (a hyperbolic tangent based win-
dow). The default kernel is tanh, see the adequate litter-
ature about interpolation kernels to learn more. The com-
mand has an option that only "shows" the kernels it has
available, producing the interpolation window on stdout.
By re-directing this output to a text file, it should be
easy to visualize them with any plotting tool such as gnu-
plot.
Parameters
Linear transforms (includes integer transforms)
-t or --translate tx ty
provides tx and ty for a translation vector. This
option can be combined with a rotation (-r) and/or
a scaling (-s) option.
-r or --rotate angle
provides an angle for the rotation, in degrees.
Negative angles are accepted. The rotation center
is the center of the image.
-s or --scale factor
provides a scaling factor. This factor needs not be
integer, i.e. a scaling by a factor 1.4142 is pos-
sible.
-T or --transform 'p1 p2 p3 p4 p5 p6'
If you know the expression of a linear transform to
apply, you can provide it through this option. Pro-
vide 6 parameters p1...p6. Enclose the parameters
in simple quotes. They are defined as a forward
affine transform from the input image to the output
image. If (x,y) are coordinates in the input image
and (u,v) coordinates in the output image, then:
u = p1.x + p2.y + p3
v = p4.x + p5.y + p6
For example, to apply a scale change of a factor 2 and a
translation vector of (+100,-50), both commands are equiv-
alent:
> warping -s 2 -t '100 -50' image.fits
> warping -T '2 0 100 0 2 -50' image.fits
Providing a linear transform allows also other image
deformations than just rotation, scale and translation.
Polynomial transforms
Polynomial transforms need be expressed in a reversed way:
if (u,v) are the coordinates of a pixel in the warped
image, and (x,y) in the original image, the polynomial
needs to be expressed as:
x = Px(u,v)
y = Py(u,v)
Provide the two polynomial expressions through the -u and
-v options. The polynomial format on the command-line is
the following:
A polynomial is given by triplets of values. The first
value indicates the degree for u, the second one the
degree for v, and the third value is the multiplicative
coefficient. For example, 3.u^2.v is written as:
2 1 3
Another example: the polynomial is 3 + 4.u^2 + v
The expression is:
0 0 3 2 0 4 0 1 1
-u or --polyu du dv c0 ... du dv cn
Provides the coefficients for Px(u,v).
-v or --polyv du dv c0 ... du dv cn
Provides the coefficients for Py(u,v)
-A or --arcfile file.tfits
The specified file is a table with the 2d polyno-
mial that was created by is_spec_arc and that
describes the slit curvature distortion
-S or --sttrfile file.tfits
The specified file is a table with the 2d polyno-
mial that was created by is_spec_startrace and that
describes the startrace distortion
Resampling kernels
-k or --kernel name
Choose the interpolation kernel used to resample
the image. Possible choices are:
sinc - "ideal" filter (for infinite signals)
sinc2 - square sinc
lanczos - Lanczos function (2nd order)
hamming - Hamming function
hann - Hann function
tanh - Hyperbolic tangent
default - default is tanh kernel
If you do not know what these functions refer to, it is
recommended not to modify them. See documentation about
image warping to learn more about these kernels.
-w or --write
This option will have a kernel generated then
printed out to stdout. No further processing will
be done. The output data can be redirected to a
file, and/or plotted by any graphical 2d plotter
(e.g. gnuplot).
Example:
> warping -k hamming -w > hamming.dat
Algorithm
Resampling is done by applying a resampling kernel in
image space, over the 16 closest neighbors. The algorithm
is the following:
For each pixel position in the resulting image, compute
the position of the source pixel in the original image,
interpolate its value over the 16 closest neighbors with
the chosen kernel. Pixel positions falling out of the
original image are assigned a null value.
Files
Input files shall all comply with FITS format.
Bugs
The interpolation over 16 neighbors implies border effects
which are not handled. Interpolation artifacts can be seen
close to high spatial frequencies (especially on bad pix-
els).
Only images shall be warped, not data cubes. This exten-
sion may be implemented in a future release.
In linear transforms: applying only a rotation turns the
image around its center. If you try to combine a rotation
and a scaling or a translation, rotation is then done rel-
ative to the pixel (0,0), i.e. the lower left pixel of
the image.
Radial transforms are not implemented yet.