.help florentz Jan91 ftools.fimage
.ih
NAME
florentz -- Convolve a FITS image with an elliptical Lorentzian function
.ih
USAGE
florentz infile outfile sigma
.ih
PARAMETERS
.ls infile [file name]
Input FITS file and extension number to be convolved with the elliptical
 Lorentzian function.
.le
.ls outfile [file name]
Output FITS file where the convolved image will be written. 
.le
.ls sigma [double]
The sigma of the Lorentzian function in pixels along the direction \fItheta\fR
of the major axis of the Lorentzian function.
.le
.ls (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 \fIratio\fR is 1 the Lorentzian function is circular.
.le
.ls (theta = 0.0) [double]
The position of the major axis of the elliptical Lorentzian function.
\fITheta\fR is measured counter-clockwise from the x axis and must be between
0 and 180 degrees.
.le
.ls (nsigma = 4.0) [double]
The distance along the major axis of the Lorentzian function at which
the kernel is truncated in \fIsigma\fR pixels.
.le
.ls (boundary = "nearest") [double]
The algorithm used to compute the values of the out of bounds pixels. The
options are:
.ls nearest
Use the value of the nearest boundary pixel.
.le
.ls constant
Use a constant value.
.le
.ls reflect
Generate a value by reflecting around the boundary.
.le
.ls wrap
Generate a value by wrapping around to the opposite side of the image.
.le
.le
.ls (constant = 0.0) [double]
The constant for constant-valued boundary extension.
.le
.ls (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.
.le
.ls (nullval = 0.0) [double]
Value to substitute for any undefined pixels within the image.
.le
.ls (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.
.le
.ls (copyall = no) [boolean]
If true, all other extensions, including the primary array are copied
to the output file.
.le
.ls (clobber = no) [boolean]
If true, an existing output file of the same name will be overwritten.
.le

.ih
DESCRIPTION

FLORENTZ convolves the FITS image in \fIinput\fR with the
Lorentzian kernel specified by \fIsigma\fR, \fIratio\fR, \fItheta\fR and
\fInsigma\fR and places the convolved images in \fIoutput\fR FITS file.
Out of bounds pixels are computed using the algorithm
specified by \fIboundary\fR. 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 \fIyes\fR 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 \fIno\fR 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 \fIyes\fR  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 \fIno\fR 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.

.nf
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)
.fi

.ih
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

.ih
BUGS
.ih
SEE ALSO
fboxcar, fgauss
.endhelp
