FLORENTZ (Jan91) ftools.fimage FLORENTZ (Jan91)
NAME
florentz -- Convolve a FITS image with an elliptical Lorentzian
function
USAGE
florentz infile outfile sigma
PARAMETERS
infile [file name]
Input FITS file and extension number to be convolved with the
elliptical Lorentzian function.
outfile [file name]
Output FITS file where the convolved image will be written.
sigma [double]
The sigma of the Lorentzian function in pixels along the
direction theta of the major axis of the Lorentzian function.
(ratio = 1.0) [double]
The ratio of the sigma in the minor axis direction to the sigma
in the major axis direction of the Lorentzian function. If
ratio is 1 the Lorentzian function is circular.
(theta = 0.0) [double]
The position of the major axis of the elliptical Lorentzian
function. Theta is measured counter-clockwise from the x axis
and must be between 0 and 180 degrees.
(nsigma = 4.0) [double]
The distance along the major axis of the Lorentzian function at
which the kernel is truncated in sigma pixels.
(boundary = "nearest") [double]
The algorithm used to compute the values of the out of bounds
pixels. The options are:
nearest
Use the value of the nearest boundary pixel.
constant
Use a constant value.
reflect
Generate a value by reflecting around the boundary.
wrap
Generate a value by wrapping around to the opposite side of
the image.
(constant = 0.0) [double]
The constant for constant-valued boundary extension.
(datatype = "-") [character]
The data type for the resulting smoothed image. A "-" or " "
results in storing the smoothed image with the same data type
as the original input image. The letter B or b represents byte,
the letter I or i represents short integer, the letter J or j
represents integer, the letter E or e represents single
precision reals and the letter D or d represents double
precision reals.
(nullval = 0.0) [double]
Value to substitute for any undefined pixels within the image.
(copyprime = yes) [boolean]
If true, all of the primary header keywords, the primary array
(if any) and all of the extension keywords of the first input
file are copied to the output file. If false, only minimal
headers are created.
(copyall = no) [boolean]
If true, all other extensions, including the primary array are
copied to the output file.
(clobber = no) [boolean]
If true, an existing output file of the same name will be
overwritten.
DESCRIPTION
FLORENTZ convolves the FITS image in input with the Lorentzian
kernel specified by sigma, ratio, theta and nsigma and places the
convolved images in output FITS file. Out of bounds pixels are
computed using the algorithm specified by boundary. The FITS image
to be smoothed can be in either the primary array or in an image
extension. The resulting smoothed image will be placed in either
the output files primary array or in an image extension depending
on three things; the location of the image in the input file, the
value of the copyprime flag and the value of the copyall flag.
If the input image is in the primary array then the resulting image
will always be placed in the primary array. In this case, if the
copyprime flag is yes then all the keywords from the input primary
header will be copied to the output primary header, otherwise only
the required keywords will be placed in the output primary header.
Setting the copyall flag will cause all the FITS extensions in the
input FITS file to be copied over to the output FITS file.
If the input image is in an image extension the the resulting image
will be placed in one of three places depending on the values of
the copyprime and copyall flags. If the copyprime flag is no the
the resulting smoothed image will always appear in the primary
array. If the copyall flag is also set then all extension will be
copied to the output FITS file and the input primary array will be
stored in the image extension that the image was originally stored
in the input FITS file. If the copyprime flag is yes then the
primary array of the input FITS file will always be copied over to
the primary array of the output FITS file. In this case, if the
copyall flag is no then the smoothed image will be stored in the
first extension of the output FITS file, otherwise the smoothed
image will appear in the same extension in both the input and
output FITS file and all other extensions will be copied to the
output FITS file.
The Lorentzian kernel has an elliptical cross-section and Lorentzian
profile and is defined mathematically as follows.
1. Circularly Symmetric Lorentzian Function
ratio = 1 theta = 0.0 N = normalization factor
G = N * 1.0 / (1.0 + (r / sigma) ** 2)
2. Elliptical Lorentzian Function (Theta = 0, 90 or 180)
sigmax = sigma sigmay = ratio * sigmax N = normalization factor
A = cos (theta) ** 2 / sigmax ** 2 - sin (theta) ** 2 / sigmay ** 2
B = 0.0
C = sin (theta) ** 2 / sigmax ** 2 + cos (theta) ** 2 / sigmay ** 2
z = A * x ** 2 + B * x * y + C * y ** 2
G = N * 1.0 / (1.0 + z)
3. Elliptical Lorentzian Function (Arbitrary Theta)
sigmax = sigma sigmay = ratio * sigmax N=normalization factor
A = cos (theta) ** 2 / sigmax ** 2 - sin (theta) ** 2 / sigmay ** 2
B = -2 * (1 / sigmax ** 2 - 1 / sigmay ** 2) * sin (theta) * cos (theta)
C = sin (theta) ** 2 / sigmax ** 2 + cos (theta) ** 2 / sigmay ** 2
z = A * x ** 2 + B * x * y + C * y ** 2
G = N * N * 1.0 / (1.0 + z)
EXAMPLES
1. Convolve an image with a circular Lorentzian function of sigma
2.0, and size 4.0 sigma using nearest neighbor boundary extension.
cl> florentz image.fits gimage.fits 2.0
2. Convolve an image with an elliptical Lorentzian function whose
sigma in the major and minor axis direction is 2.0 and 1.5
respectively, and whose position angle is 45 degrees, using wrap
around boundary extension.
cl> florentz img.fits gimg.fits 2.0 ratio=0.75 theta=45.0
bound=wrap
3. Convolve an image in the 3rd extension with a circular
Lorentzian function of sigma 2.0, and size 4.0 sigma using nearest
neighbor boundary extension and store the resulting image in the
primary array.
cl> florentz imgx.fits[3] gimg.fits 2.0 copyprime=no
BUGS
SEE ALSO
fboxcar, fgauss