; CONVL
;---------------------------------------------------------------
;! convolves an image with a gaussian or another image
;# Task Imaging AP
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2002-2004, 2008
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
CONVL     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
CONVL:  Task to convolve two images.
                                   Input image.
INNAME                                Image name (name)
INCLASS                               Image name (class)
INSEQ              0.0      9999.0    Image name (seq. #)
INDISK             0.0         9.0    Image disk drive #
OPCODE                             Operation desired:
                                      GAUS, IMAG, DCON, DGAU
                                      GAUC
BLC                                Bottom left corner
TRC                                Top right corner
                                   Convolving image (IMAG, DGAU)
IN2NAME                               Image name (name)
IN2CLASS                              Image name (class)
IN2SEQ             0.0      9999.0    Image name (seq. #)
IN2DISK            0.0         9.0    Image disk drive #
                                   Convolved image.
OUTNAME                               Image name (name)
OUTCLASS                              Image name (class)
OUTSEQ            -1.0      9999.0    Image name (seq. #)
OUTDISK            0.0         9.0    Image disk drive #
IMSIZE                             Size of box to find position
                                   of max in output image (IMAC)
BMAJ            -999.9             FWHM(asec) maj. axis output.
                                   beam - required except IMAG
BMIN            -999.9             FWHM(asec) min. axis output
                                   beam.
BPA             -360.0       360.0 position angle
FACTOR                             Unit conversion factor;
                                   clip inv Gaussian level DCON
DOBLANK         -1.0         1.0   > 0 => reblank output images
                                   where input was blanked
BADDISK                            Disks to avoid for scratch.
----------------------------------------------------------------
CONVL
Type: Task
Use:  CONVL convolves your map with a either an eliptical gaussian or a
      specified convolving image.  Strictly, only the inner quarter of
      the map is properly convolved, but for the Gaussian this problem
      may not be apparent.  CONVL uses a 2D FFT, and so it cannot
      properly handle images containing blanks.  It will (in 31DEC04)
      replace blanks with 0.0, do the convolution, and then put the
      blanks back.  Nonetheless, the effect of the 0.0 will be felt in
      non-blank pixels.  The second image must not contain blanked
      pixels.  CONVL surrounds images with sizes other than a power of
      2 with zeroes up to the next power of 2, convolves using the 2D
      FFT, and then removes the borders for output.
Adverbs:
  INNAME......The input image name.     Standard defaults.
  INCLASS.....The input image class.    Standard defaults.
  INSEQ.......The input image seq. #.   0 => highest.
  INDISK......The input image disk drive #. 0 => any.
  OPCODE......A code indicating the desired operation.
              'GAUS' => convolve the image with the specified Gaussian.
              'IMAG' => convolve the image1 with the second image.
              'IMAC' => crosscorelate the image1 with the second image.
              'DCON' => deconvolve the image from specified Gaussian.
              'DGAU' => convolve the image with the deconvolution of the
                    Gaussian and the second image (Gaussian divided by
                    image in Fourier space)
              blank => 'GAUS'
  BLC.........The bottom left corner of a subimage to be convolved.
                 (0's => 1,1,1,1,1,1,1)
  TRC.........The top right corner of the subimage to be convolved.
                 (0's => all of image from BLC)
  IN2NAME.....The convolving image name.  Standard defaults.  Must be
              same size and cell spacing as INNAME.
  IN2CLASS....The convolving image class. Standard defaults.
  IN2SEQ......The convolving image seq . #. 0 => highest.
  IN2DISK.....The convolving image disk drive #.  0 => any
  OUTNAME.....The output image name.   Standard defaults.
  OUTCLASS....The output image class.  Standard defaults.
  OUTSEQ......The output image seq. #. 0 => highest unique.
              Input file (only) may be overwritten.
  OUTDISK.....The clean disk drive no. 0 => highest with space
  IMSIZE......Size of the box used to calculate max position
              at the output image.
              Used only if OPCODE='IMAC'
              Must be odd!!!
              0 => 5, 5
  BMAJ........Required for all OPCODEs except IMAG: the FWHM (asec)
              major axis of the desired output beam.  0 -> Clean beam
              for DCON only, for rest it is an error.  Other than
              IMAG, it will be deconvolved from the clean beam if the
              input image is a clean image.  If the deconvolution
              fails, the program will terminate.
  BMIN........The FWHM (asec) minor axis of the output beam.
              If <= 0 BMIN = BMAJ
  BPA.........The position angle in the unrotated image of BMAJ.
  FACTOR......All OPCODEs except DCON: the conversion factor for the
              image units.  This value of FACTOR if specified should
              be the ratio of the new beam area to the old beam area.
              If FACTOR is > 0.0, it will be used to convert from
              JY/(old beam) to JY/(new beam).  If FACTOR is 0.0 or
              less, it will be determined from the output beam size
              and any CLEAN beam stored in the catalog.  If FACTOR is
              not given and cannot be computed it is set to 1.0 and
              the map units are changed to "UNDEFINE".  If flux per
              pixel output is desired then use FACTOR=1.0.

              If input image is measured in Jy/pixel and OPCODE=GAUS, then
                 the convolved image is scaled by FACTOR/(NPIXATBEAM))
                 where NPIXATBEAM is number of pixels at the convolving
                       beam; NPIXATBEAM = BMIN*BMAJ*ALFA
                       BMIN, BMAJ are in  pixels,
                       ALFA = PI/(4*ln(2))=1.13309
                 If FACTOR=0 then
                    the output image is not scaled(multiplied by 1)

              DCON only: FACTOR is instead the limit in the value of
              1/Gaussian.  <= 1.01 => 1000.
  DOBLANK.....> 0 => reblank those pixels that were blanked in the
              input image.  This still leaves pixels around the
              blanked affected by the use of 0.0 in the convolution.
              <= 0 => leave previously blanked pixels at whatever the
              convolution produced from the 0.0 used instead of the
              blank value.
  BADDISK.....This array contains the numbers of disks on which it is
              desired that scratch files not be located.  BADDISK has no
              effect on input and output maps.
----------------------------------------------------------------
A remark about convolving a map which has been CLEANed
      (added by DCW, 15 October 84)

In the help text above under the heading for BMAJ it says:
"[BMAJ] will be deconvolved from the clean beam if the image is
a clean image." What this really means is that CONVL will
attempt to produce a map which has the desired clean beam
shape, and in the process it will account for an existing beam
as declared in the header. This is done by deriving the
parameters of a Gaussian which when convolved with the existing
clean beam will produce the desired beam (the parameters of
this beam are listed in the history file). Obviously this
scheme only works when the desired beam is larger than the
existing beam (use the DGAU option if you want to deconvolve).
Please note that AIPS has tools for inserting clean beam
parameters into headers if they are not already there.


A preliminary explanation of the 'DGAU' option
      (added by DCW, 26Sept84)

Suppose that the second image contains the beam pattern of the
first image. Then DGAU will convert the effective beam of the
input image to the specified Gaussian. If the specified
Gaussian is narrower than the original beam this amounts to a
simple linear deconvolution scheme. The operation is done by
dividing the transform of the specified Gaussian by the
transform of the second image, and multiplying the quotient by
the input image. The quotient is set to zero when the transform
of the second image is zero.

An important application of DGAU is "cleaning up" the seeing
profile of an optical image. This is done by specifying a
circular Gaussian which is a good fit to the observed profile
(i.e., the second image). DGAU will then correct for the
ellipticity of the profile and its excess intensity in the
wings, producing an image which has a nice Gaussian beam,
although no resolution enhancement.

